@waaskey/sdk 0.4.1 → 0.6.0

package/README.md

@@ -80,14 +80,41 @@ const waaskey = new Waaskey({
   baseUrl: process.env.WAASKEY_API_URL!,
   mpc,
   shareStore: new EncryptedShareStore(new MemoryKeyValueStore(), process.env.SHARE_SECRET!),
-  primePool: new PrimePool(mpc),
+  // `concurrency` only helps a WORKER-BACKED core: inline WASM generation shares the calling
+  // thread, so overlapping the searches finishes no sooner and delays the first usable prime.
+  primePool: new PrimePool(mpc, { concurrency: 4 }),
 });
 
 // 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 recoveryCode = generateRecoveryCode();
+let mustShowTheCode = true;
+
+const wallet = await waaskey.wallets.create(
+  { chain: 'ethereum' },
+  {
+    backup: {
+      recoveryCode,
+      totpSecret,
+      email,
+      // Enrols a passkey INSTEAD of the code where the device can produce a PRF, and the code
+      // where it cannot. Never both: the recovery gate is an AND of every enrolled factor, so a
+      // wallet holding both would be bricked by losing either one.
+      passkeyEnroller: () => new PasskeyPrfSecretProvider().enroll({ userName: email }),
+    },
+    // Which one actually happened — the app cannot infer it, because enrolment can fall back for
+    // reasons it cannot see.
+    onRecoveryEnrolled: ({ strongFactor }) => {
+      mustShowTheCode = strongFactor === 'recovery_code';
+    },
+  },
+);
+
+// Show the code ONLY if it is what guards the wallet. Telling a passkey user to write down a code
+// nobody will ever ask them for is how a recovery screen teaches people to ignore it.
+if (mustShowTheCode) showRecoveryCode(recoveryCode);
+
 const signature = await wallet.sign(digestHex);
 ```
 
@@ -168,6 +195,8 @@ const { items } = await wallet.signatures({ page: 1, limit: 20 });
 | `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.                                                                           |
+| `waaskey.sessionKeys.list(walletId?, signal?)`                                                           | The tenant's active session keys (delegated, scoped permissions).                                                                            |
+| `waaskey.sessionKeys.send(params, signal?)`                                                              | Sign a call with a session key and submit it as a UserOperation.                                                                             |
 
 `create` / `sign` accept `{ signal }` for cancellation; `create` also takes
 `{ waitForActive?, activationTimeoutMs?, pollIntervalMs? }`.
@@ -176,6 +205,87 @@ Errors are thrown as `WaaskeyError` with a typed `code` (e.g. `unauthorized`,
 `forbidden`, `validation`, `device_core_required`, `keygen_failed`, `aborted`) plus
 `status?` and `details?` — branch on `error.code`, never on the message text.
 
+### Session keys — acting with a delegated permission
+
+A session key is a scoped, time-limited signer a wallet granted: certain contracts, certain
+selectors, up to a value, a bounded number of calls. `send` prepares the UserOperation server-side,
+signs its hash with the key, and submits exactly those fields — the gas and paymaster values are
+part of what the signature covers, so a locally-guessed op would produce a signature for an
+operation the bundler never sees.
+
+```ts
+const { userOpHash } = await waaskey.sessionKeys.send({
+  sessionKeyId,
+  privateKey, // the granted key's PRIVATE half — signs locally, never sent
+  sender, // the smart account it acts for
+  chainId: 'evm:1',
+  callData, // ABI-encoded execute calldata
+  contract, // checked against the key's allowlist
+  selector,
+  valueWei: '0x0', // checked against the key's cap
+});
+```
+
+### Asking a user for a permission
+
+An app that wants a permission asks for one and sends the user to their wallet to answer:
+
+```ts
+const waaskey = new Waaskey({ apiKey, baseUrl, walletUrl: 'https://wallet.example.com' });
+
+const req = await waaskey.sessionKeys.request({
+  walletId,
+  label: 'Dungeon Quest — one battle',
+  scope: { allowedContracts: [game], maxCalls: 50, periodSeconds: 3600, maxCallsPerPeriod: 10 },
+  expiresAt: new Date(Date.now() + 24 * 3600_000),
+  requesterId, // your registered app — the wallet shows the domain you proved you own
+});
+
+showQrCode(req.url); // or open it; this is where the user answers
+
+const { status, key, narrowed } = await waaskey.sessionKeys.waitForDecision(req.sessionKeyId, {
+  asked: scope, // supply it to learn whether the user accepted less
+});
+```
+
+**The private key never travels.** `request` generates the keypair locally and registers only its
+public half, so nothing secret is in the request, in the link, or in the wallet — `req.privateKey`
+is yours to keep, and there is no way to fetch it later. That is also why the user is never asked to
+copy a key out of a wallet UI.
+
+**The user may narrow the request, never widen it.** They can shorten the duration or cut the
+amounts; the server refuses anything wider than what was asked. `narrowed: true` says they accepted
+less, so your app can adapt rather than failing opaquely on its first call outside the smaller scope.
+
+`waitForDecision` polls rather than waiting for a redirect back — a user answering on their phone,
+or closing the tab, would otherwise strand you with no answer. A refusal comes back as
+`status: 'declined'` (an answer, not an error); a request nobody answers throws
+`permission_request_timeout`.
+
+**Two credentials, and they are not interchangeable.** The client's `apiKey` must carry the `SIGN`
+scope — the session private key alone does not reach the API — while the private key is what
+actually authorizes the operation on-chain. This surprises everyone once.
+
+A refused call says WHY, because the fixes are opposite: `permission_expired`,
+`permission_revoked`, `permission_scope`, `permission_value_exceeded`, `permission_exhausted`,
+`permission_rate_limited`. The first three mean "re-request the permission", `permission_scope` and
+`permission_value_exceeded` mean "change the call", and `permission_rate_limited` means "the same
+call succeeds in the next period" — a grant may cap both how much it is worth in total and how fast
+it may be spent, so a spent period is not a spent permission.
+
+A listed permission carries the name it was granted under (`label`), the app that asked for it
+(`requesterId`) and the policy paying its gas (`paymasterPolicyId`). Resolve the requester to show
+who is asking:
+
+```ts
+const app = await waaskey.sessionKeys.requester(key.requesterId!);
+// app.origin is identity ONLY when app.status === 'verified' — that means the domain itself
+// published a document naming the tenant. `name` and `iconUrl` are the app's own claims.
+```
+
+The code comes from the server, not from its wording: it is read off the refusal's `code` field,
+and matching the message is only a fallback for a server that predates it.
+
 ### Secure share storage
 
 The device key share is the user's half of the key. `EncryptedShareStore` seals it