@waaskey/sdk 0.1.0 → 0.2.0

package/README.md

@@ -4,24 +4,33 @@ Official TypeScript SDK for [Waaskey](https://waaskey.com) — embedded, non-cus
 **MPC wallets** for your app. Create wallets and sign transactions where the private
 key is never assembled in one place (2-of-3 threshold ECDSA, no seed phrase).
 
-> **Early access (v0.0.x).** The public API is taking shape and may change before
+> **Early access (v0.2.x).** The public API is taking shape and may change before
 > `1.0.0`. Pin an exact version.
 
 ## Install
 
 ```bash
-pnpm add @waaskey/sdk
+pnpm add @waaskey/sdk @waaskey/client-wasm
 ```
 
+`@waaskey/client-wasm` is the WASM MPC engine `WasmMpcCore` loads at runtime — it is
+an **exact-pinned optional peer** (the SDK refuses a mismatched version), so install
+it alongside the SDK for any app that creates wallets or signs. Passkey / step-up
+flows additionally need the optional peer `@simplewebauthn/browser`.
+
 ## Quickstart
 
 ```ts
-import { Waaskey, WasmMpcCore, EncryptedShareStore } from '@waaskey/sdk';
+import { Waaskey, WasmMpcCore, EncryptedShareStore, loadClientWasm } from '@waaskey/sdk';
+
+// A secret YOU derive per user (session token, passkey PRF output, device secret) —
+// it keys the AES-256-GCM sealing of the local key share; never hardcode it.
+const sessionSecret = await deriveUserSessionSecret();
 
 const waaskey = new Waaskey({
   apiKey: process.env.WAASKEY_PUBLISHABLE_KEY!,
   // Non-custodial: the device runs its half of the ceremony and seals its key share.
-  mpc: new WasmMpcCore(loadClientWasm), // device-party crypto core (WASM)
+  mpc: new WasmMpcCore(loadClientWasm), // dynamic-imports @waaskey/client-wasm
   shareStore: EncryptedShareStore.browser(sessionSecret), // sealed in IndexedDB
 });
 
@@ -33,6 +42,56 @@ const wallet = await waaskey.wallets.create({ chain: 'ethereum' });
 const signature = await wallet.sign(digestHex);
 ```
 
+**Reusing an existing wallet:** persist `wallet.id` (`wlt_…`) next to your user record
+and load it later with `waaskey.wallets.get(id)` — the sealed device share is already
+in the `shareStore` under that id, so `sign`/`send` work as soon as the sealing secret
+is available again. Forgot the ids? `waaskey.wallets.list()` pages through the
+tenant's wallets. On a brand-new device the share is restored via _Multi-factor
+recovery_ (below), not re-created.
+
+### Node.js (no browser)
+
+The same flow works server-side on Node ≥ 22 (global `fetch`, `WebSocket` and WebCrypto
+are built in). Two things differ from the browser: the wasm engine is loaded from disk
+(Node's `fetch` can't read file paths), and there is no IndexedDB — pass
+`MemoryKeyValueStore` (or your own `KeyValueStore`, e.g. DB-backed). Generate the
+Paillier primes **before** the ceremony with a `PrimePool` — inline generation takes
+minutes of single-threaded CPU and can outlive the server party's ceremony timeout:
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { Waaskey, WasmMpcCore, EncryptedShareStore, MemoryKeyValueStore, PrimePool, generateRecoveryCode } from '@waaskey/sdk';
+
+const require = createRequire(import.meta.url);
+
+// Node wasm loader: read the bytes from the installed package and initialize with them.
+async function loadClientWasmNode() {
+  const mod = await import('@waaskey/client-wasm');
+  const bytes = await readFile(require.resolve('@waaskey/client-wasm/client_wasm_bg.wasm'));
+  await mod.default(await WebAssembly.compile(bytes));
+  return mod;
+}
+
+const mpc = new WasmMpcCore(loadClientWasmNode);
+const waaskey = new Waaskey({
+  apiKey: process.env.WAASKEY_API_KEY!,
+  mpc,
+  shareStore: new EncryptedShareStore(new MemoryKeyValueStore(), process.env.SHARE_SECRET!),
+  primePool: new PrimePool(mpc),
+});
+
+// Off the hot path (boot/idle): pre-generate the primes so create() takes seconds.
+await waaskey.wallets.prewarm('ethereum');
+
+const recoveryCode = generateRecoveryCode(); // show it to the user once
+const wallet = await waaskey.wallets.create({ chain: 'ethereum' }, { backup: { recoveryCode, totpSecret, email } });
+const signature = await wallet.sign(digestHex);
+```
+
+> A wallet created this way is non-custodial with the _server you run this on_ acting
+> as the "device" — its share lives in your `shareStore`. Guard that store accordingly.
+
 ### Send a transaction — WaaS signs, **you** broadcast
 
 WaaS is a **signing service, not a broadcaster** (non-custodial: it never owns the
@@ -55,8 +114,9 @@ integrator's concern.
 
 ### Custody policy — choose the threshold topology (advanced)
 
-`wallets.create({ chain })` defaults to the **embedded 2-of-3** topology (the platform
-alone can meet the threshold — the honest default posture). To change the `(t, n)`
+`wallets.create({ chain })` defaults to the **non-custodial 2-of-3** topology
+`[device, server, user_backup]` — the platform holds 1 share < t=2, so it can never
+sign alone (`custodyType: 'shared'`, `isNonCustodial: true`). To change the `(t, n)`
 threshold or the custody guarantee, pass a custody policy; the SDK validates it
 client-side and the backend enforces the attested invariant `platformShares < t ⟺
 non-custodial`:
@@ -65,14 +125,14 @@ non-custodial`:
 const wallet = await waaskey.wallets.create({
   chain: 'ethereum',
   threshold: 2, // t
-  parties: ['device', 'backup', 'server'], // n = 3 party roles
+  parties: ['device', 'user_backup', 'server'], // n = 3 well-known party roles
   custodyKinds: ['user_device', 'user_backup', 'platform_signer'], // parallel to parties
   custodyType: 'shared', // requested posture — the server refuses (400) on a mismatch
 });
 
 // The returned wallet surfaces the attestation so you can display the guarantee:
 wallet.threshold; // 2
-wallet.parties; // ['device','backup','server']
+wallet.parties; // ['device','user_backup','server']
 wallet.custodyKinds; // ['user_device','user_backup','platform_signer']
 wallet.platformShareCount; // 1
 wallet.custodyType; // 'shared'
@@ -96,15 +156,16 @@ const { items } = await wallet.signatures({ page: 1, limit: 20 });
 
 ## API
 
-| Method                                                                                                   | Description                                                                                            |
-| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `new Waaskey({ apiKey, mpc, shareStore, baseUrl?, fetch? })`                                             | Create a client. `mpc` + `shareStore` are required to create wallets.                                  |
-| `waaskey.wallets.create({ chain, label?, threshold?, parties?, custodyKinds?, custodyType? }, options?)` | Create (keygen + sealed share). Optional custody policy (default embedded 2-of-3). Returns a `Wallet`. |
-| `waaskey.wallets.get(id, options?)`                                                                      | Load an existing wallet.                                                                               |
-| `wallet.sign(digestHex, options?)`                                                                       | Sign a 32-byte digest with the wallet's MPC key.                                                       |
-| `wallet.send(params, options?)`                                                                          | Build + MPC-sign a tx. Returns the **signed raw tx** (you broadcast).                                  |
-| `wallet.signatures(query?, options?)`                                                                    | The wallet's signing activity (paginated).                                                             |
-| `waaskey.broadcast(signedTx, { rpcUrl })`                                                                | **Optional** best-effort submit of a signed tx from your own node.                                     |
+| Method                                                                                                   | Description                                                                                                                                  |
+| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `new Waaskey({ apiKey, mpc, shareStore, baseUrl?, fetch? })`                                             | Create a client. `mpc` + `shareStore` are required to create wallets.                                                                        |
+| `waaskey.wallets.create({ chain, label?, threshold?, parties?, custodyKinds?, custodyType? }, options?)` | Create (keygen + sealed share). Optional custody policy (default: non-custodial 2-of-3 `[device, server, user_backup]`). Returns a `Wallet`. |
+| `waaskey.wallets.list(query?, options?)`                                                                 | List the tenant's wallets, newest first (paginated `WalletData` rows).                                                                       |
+| `waaskey.wallets.get(id, options?)`                                                                      | Load an existing wallet.                                                                                                                     |
+| `wallet.sign(digestHex, options?)`                                                                       | Sign a 32-byte digest with the wallet's MPC key.                                                                                             |
+| `wallet.send(params, options?)`                                                                          | Build + MPC-sign a tx. Returns the **signed raw tx** (you broadcast).                                                                        |
+| `wallet.signatures(query?, options?)`                                                                    | The wallet's signing activity (paginated).                                                                                                   |
+| `waaskey.broadcast(signedTx, { rpcUrl })`                                                                | **Optional** best-effort submit of a signed tx from your own node.                                                                           |
 
 `create` / `sign` accept `{ signal }` for cancellation; `create` also takes
 `{ waitForActive?, activationTimeoutMs?, pollIntervalMs? }`.
@@ -124,6 +185,32 @@ IndexedDB (`MemoryKeyValueStore` for tests/SSR). Wipe everything on logout:
 await shareStore.clear();
 ```
 
+#### Passkey-derived secret (recommended)
+
+The strongest source for the sealing secret is a **passkey with the WebAuthn PRF
+extension** (`PasskeyPrfSecretProvider`): the 32-byte secret only materializes after
+the user touches their authenticator (or passes biometrics) and never sits on disk —
+malware that steals the IndexedDB ciphertext cannot decrypt it in the background.
+Needs the optional peer `@simplewebauthn/browser`.
+
+```ts
+import { PasskeyPrfSecretProvider, isPrfSupported } from '@waaskey/sdk';
+
+const prf = new PasskeyPrfSecretProvider();
+
+// Onboarding — register a PRF-capable passkey (one authenticator touch).
+// Persist credentialId + salt anywhere (not secret); keep `secret` in memory only.
+const { credentialId, salt, secret } = await prf.enroll();
+
+// Every later session — unlock with the same passkey (another touch).
+const { secret: sessionSecret } = await prf.unlock(credentialId, { salt });
+
+const shareStore = EncryptedShareStore.browser(sessionSecret);
+```
+
+Feature-detect with `isPasskeySupported()` / `isPrfSupported()` and fall back to a
+session-derived secret where PRF is unavailable.
+
 ### Multi-factor recovery
 
 Back up the device share so a user can recover after losing their device. The share
@@ -174,6 +261,8 @@ const waaskey = new Waaskey({
 
 const eth = await waaskey.balances.getBalance('ethereum', wallet.address!);
 // → { raw: 1000000000000000000n, decimals: 18, symbol: 'ETH', formatted: '1' }
+// (`symbol` is optional in the type — present for built-in EVM chains, may be
+//  undefined for a custom provider that doesn't supply one)
 
 const usdc = await waaskey.balances.getTokenBalance('ethereum', usdcAddress, wallet.address!, { symbol: 'USDC' });
 ```

package/dist/index.cjs

@@ -1286,6 +1286,17 @@ var Wallets = class {
     if (curve === "ed25519") return;
     await this.deps.primePool?.ensure(curve);
   }
+  /**
+   * List the tenant's wallets, newest first (paginated). Returns plain {@link WalletData}
+   * rows — pass an `id` to {@link get} to obtain a signing-capable {@link Wallet}.
+   */
+  async list(query = {}, options = {}) {
+    const qs = new URLSearchParams();
+    if (query.page !== void 0) qs.set("page", String(query.page));
+    if (query.limit !== void 0) qs.set("limit", String(query.limit));
+    const suffix = qs.toString() ? `?${qs}` : "";
+    return this.http.request("GET", `/v1/wallets${suffix}`, void 0, options.signal);
+  }
   /** Load an existing wallet by id. */
   async get(id, options = {}) {
     const data = await this.http.request("GET", `/v1/wallets/${id}`, void 0, options.signal);
@@ -1868,7 +1879,7 @@ var Waaskey = class {
     this.auth = new Auth(http);
     this.members = new Members(http);
     http.useMemberAccessToken(() => this.members.accessToken);
-    this.wallets = new Wallets(http, { mpc: options.mpc, shareStore: options.shareStore, analytics });
+    this.wallets = new Wallets(http, { mpc: options.mpc, shareStore: options.shareStore, primePool: options.primePool, analytics });
     this.recovery = new Recovery(http, { shareStore: options.shareStore, analytics });
     this.reshare = new Reshare(http, { mpc: options.mpc, shareStore: options.shareStore, analytics });
     this.balances = new Balances(options.chains, options.fetch);
@@ -2206,7 +2217,7 @@ function decodePublicKey(sharedPublicKeyJson) {
 
 // src/mpc/load-wasm.ts
 var CLIENT_WASM_PACKAGE = "@waaskey/client-wasm";
-var CLIENT_WASM_VERSION = "0.2.0";
+var CLIENT_WASM_VERSION = "0.2.1";
 async function verifyWasmIntegrity(bytes, expectedSha384) {
   if (!expectedSha384 || !expectedSha384.startsWith("sha384-")) {
     throw new Error("Waaskey: an expected SHA-384 integrity hash (sha384-<base64>) is required to load the wasm MPC core.");