@waaskey/react 0.3.1 → 0.4.0

package/README.md

@@ -2,51 +2,153 @@
 
 React hooks + provider for the [Waaskey](https://waaskey.com) SDK — embedded,
 non-custodial **MPC wallets**. A thin layer over [`@waaskey/sdk`](../sdk); the same
-hooks work in React Native.
+hooks work in React Native (via [`@waaskey/react-native`](../react-native)).
 
 ## Install
 
+`@waaskey/sdk` and `react` are **peer dependencies** — the SDK holds your end-user session and
+the MPC/share state, so a second copy in the tree would mean a second client and a lost session.
+
 ```bash
 pnpm add @waaskey/react @waaskey/sdk @waaskey/client-wasm react
 ```
 
+`@waaskey/client-wasm` carries the browser MPC engine; `qrcode` is optional (the Receive tab shows
+the address either way), as is `@simplewebauthn/browser` (only for passkey sign-in).
+
 ## Use
 
 ```tsx
-import { WaaskeyProvider, useCreateWallet, useBalance } from '@waaskey/react';
-import { WasmMpcCore, EncryptedShareStore } from '@waaskey/sdk';
+import { useMemo, useState } from 'react';
+import { ConnectModal, WaasProvider, useAuth, useBalance, useCreateWallet } from '@waaskey/react';
+import { EncryptedShareStore, WasmMpcCore, loadClientWasm } from '@waaskey/sdk';
+import type { EmbeddedSession } from '@waaskey/sdk';
+
+export default function App() {
+  // The device share is sealed with a secret derived from the signed-in user, so the MPC pieces
+  // can only be wired once you have a session. `useMemo` keeps the options (and therefore the
+  // client) stable — see "Client identity" below.
+  const [session, setSession] = useState<EmbeddedSession | null>(null);
+  const options = useMemo(() => {
+    const base = { apiKey: import.meta.env.VITE_WAASKEY_KEY as string };
+    if (!session) return base;
+    return {
+      ...base,
+      mpc: new WasmMpcCore(loadClientWasm),
+      shareStore: EncryptedShareStore.browser(`${session.token.slice(0, 32)}:my-app`),
+    };
+  }, [session]);
 
-const options = {
-  apiKey: import.meta.env.VITE_WAASKEY_KEY,
-  mpc: new WasmMpcCore(loadClientWasm),
-  shareStore: EncryptedShareStore.browser(sessionSecret),
-};
-
-function App() {
   return (
-    <WaaskeyProvider options={options}>
-      <Wallet />
-    </WaaskeyProvider>
+    <WaasProvider options={options} persistSession="session">
+      <Wallet onSession={setSession} />
+    </WaasProvider>
   );
 }
 
-function Wallet() {
-  const { create, wallet, isPending } = useCreateWallet();
+function Wallet({ onSession }: { onSession: (s: EmbeddedSession) => void }) {
+  const { isAuthenticated, ready, user, logout } = useAuth();
+  const { create, wallet, isPending, error } = useCreateWallet();
   const { data: balance } = useBalance('ethereum', wallet?.address);
-  return isPending ? <Spinner /> : <button onClick={() => create({ chain: 'ethereum' })}>Create</button>;
+
+  if (!ready) return null; // a persisted session may still be restoring
+  if (!isAuthenticated) return <ConnectModal open onClose={() => undefined} onConnect={onSession} />;
+
+  return (
+    <>
+      <p>
+        {user?.email} · <button onClick={logout}>Sign out</button>
+      </p>
+      {error && <p role="alert">{error.message}</p>}
+      {wallet ? (
+        <p>
+          {wallet.address} — {balance?.formatted ?? '…'} ETH
+        </p>
+      ) : (
+        <button disabled={isPending} onClick={() => create({ chain: 'ethereum' })}>
+          {isPending ? 'Creating…' : 'Create wallet'}
+        </button>
+      )}
+    </>
+  );
 }
 ```
 
-| Export                       | Description                                             |
-| ---------------------------- | ------------------------------------------------------- |
-| `WaaskeyProvider`            | Provides a configured client (`options` or `client`).   |
-| `useWaaskey()`               | The `Waaskey` client from context.                      |
-| `useCreateWallet()`          | `{ create, wallet, error, isPending }`.                 |
-| `useWallet(id)`              | `{ data, loading, error, refresh }`.                    |
-| `useBalance(chain, address)` | `{ data, loading, error, refresh }` — client-side read. |
+Keygen runs in the browser and takes a while (Paillier safe primes) — render the pending state.
+Persist `wallet.id` in your own database and reload it later with `useWallet(id)`; the device share
+stays in the `shareStore`.
+
+### Hooks
+
+| Export                       | Description                                                         |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `useWaaskey()`               | The `Waaskey` client from context.                                  |
+| `useWaas()`                  | `{ client, theme, auth }` — the unified surface.                    |
+| `useAuth()`                  | `{ user, session, isAuthenticated, ready, logout, setSession, … }`. |
+| `useUser()`                  | The signed-in end-user, or `undefined`.                             |
+| `useLogin()`                 | Headless login: email/phone OTP, Google, Firebase, passkey.         |
+| `useCreateWallet()`          | `{ create, wallet, error, isPending }`.                             |
+| `useWallet(id)`              | `{ data, loading, error, refresh }`.                                |
+| `useWallets(query?)`         | `{ data, total, loading, error, refresh }` — the tenant's wallets.  |
+| `useBalance(chain, address)` | `{ data, loading, error, refresh }` — client-side read.             |
+| `useBalances(chains, addr)`  | The same across several chains.                                     |
+| `useSend(wallet)`            | `{ send, status, result, error, reset }` — `idle → pending → sent`. |
+| `useSignatures(wallet)`      | A wallet's signing activity.                                        |
+| `useQrCode(text)`            | A QR data URL (needs the optional `qrcode` package).                |
+
+`useSend`/`useSignatures` accept a wallet **id or a loaded `Wallet`** — pass the object you already
+have to skip a `wallets.get`. Every read cancels the request it supersedes, so a slow earlier
+response can't overwrite a newer one.
 
 All of `@waaskey/sdk` is re-exported, so a single import covers types and values.
 
+### Signing in
+
+`<ConnectModal>` drives `useLogin`, and the session it establishes is published to the provider's
+shared auth state — so `useAuth()` sees it everywhere, not only inside the modal.
+
+```tsx
+<ConnectModal open={open} onClose={() => setOpen(false)} methods={['email', 'phone', 'passkey']} onConnect={(s) => console.log(s.endUser)} />
+```
+
+Google is available through `useLogin().loginWithGoogle(idToken)` — and in the modal by passing a
+`googleIdToken` resolver. Your app owns the Google button (Google Identity Services /
+`@react-oauth/google`); the kit ships no Google SDK, so without that prop the option is hidden.
+
+### Staying signed in
+
+The SDK keeps the session **in memory**, so by default a reload signs the user out. Opt in with
+`persistSession`:
+
+| Value                | Where the session goes                                                          |
+| -------------------- | ------------------------------------------------------------------------------- |
+| `'none'` _(default)_ | Memory only — a reload signs out.                                               |
+| `'session'`          | `sessionStorage` — survives a reload, cleared when the tab closes.              |
+| `'local'`            | `localStorage` — survives a restart.                                            |
+| a custom store       | Your `{ load, save, clear }` — e.g. an httpOnly cookie set by your own backend. |
+
+A session token in web storage is readable by any XSS or malicious extension, which is why the
+default is `'none'` and `'session'` is the safer built-in. On restore the token is validated with
+`auth.me()`: a token the API no longer accepts signs the user out instead of failing on the first
+call. Gate your signed-out UI on `ready`, or the app flashes the login screen on every reload.
+On React Native use `createSecureSessionStore(storage)` from `@waaskey/react-native` (Keychain /
+Keystore) — the web values do nothing there.
+
+### Client identity
+
+The client is built **once** and kept while the option values keep their identity, so an inline
+`options={{ … }}` literal is safe: primitives are compared by value, objects (MPC core, share store)
+by reference. Changing a value really does build a new client — abandoning any running ceremony and
+cached state — and the kit warns in development when that happens. The end-user session is
+re-adopted on the new client automatically, so enriching the options once after login (the pattern
+above) does not sign the user out.
+
+## Next.js (App Router)
+
+The package ships a `'use client'` directive, so importing it from a server component works; the
+components themselves still have to be rendered inside a client boundary. Build the options in a
+client module (they hold browser-only objects) and mount `<WaasProvider>` there.
+
 ## Widget kit (Privy-style, drop-in)
 
 Wrap the app once and drop in prebuilt, themeable components instead of building wallet
@@ -62,22 +164,20 @@ function App() {
     </WaasProvider>
   );
 }
-
-function Connect() {
-  const [open, setOpen] = useState(true);
-  return <ConnectModal open={open} onClose={() => setOpen(false)} onConnect={(s) => console.log(s.endUser)} />;
-}
 ```
 
 | Component / hook               | What it does                                                                             |
 | ------------------------------ | ---------------------------------------------------------------------------------------- |
-| `<WaasProvider options/theme>` | Client + theme context (alias of `WaaskeyProvider`; also accepts `client`).              |
-| `useWaas()`                    | `{ client, theme, auth }` — the unified surface.                                         |
-| `<ConnectModal>`               | Email-OTP login modal (`auth`), `onConnect(session)`.                                    |
+| `<WaasProvider options/theme>` | Client + theme + auth context (alias of `WaaskeyProvider`; also accepts `client`).       |
+| `<ConnectModal>`               | Login modal — email/phone OTP, passkey, Google; `onConnect(session)`.                    |
 | `<WalletWidget>`               | Assets / Receive (QR) / Send / Activity panel.                                           |
 | `<FundWidget>`                 | Fiat on-ramp (provider widget URL) to fund the wallet.                                   |
 | `useSignPrompt()`              | `requestSignature(tx)` → resolves on approve, rejects on cancel; renders `<SignPrompt>`. |
 
+**WaaS signs, it does not broadcast.** A send returns `result.signedTx` (plus an offline
+`result.txHash`); submitting it to a node is the integrator's step — `waaskey.broadcast(signedTx,
+{ rpcUrl })` or your own infrastructure. The widget says so on the success screen.
+
 ### Theming / white-label
 
 Pass a partial `theme` to the provider (merged onto `lightTheme`); `darkTheme` and