w3pk 0.10.2 → 0.10.3

package/docs/notes/SIWE_IMPLEMENTATION.md

@@ -0,0 +1,129 @@
+# SIWE Implementation Review
+
+Assessment of the current SIWE (EIP-4361) implementation in [`src/siwe/index.ts`](src/siwe/index.ts), with recommended improvements ordered by importance.
+
+**Verdict:** the core is solid and spec-shaped, but there is one real validation bug, several security-hardening gaps, and one DX gap.
+
+---
+
+## 1. Bug: malformed datetimes silently bypass the expiration check
+
+**Location:** `validateSiweMessage` — [`src/siwe/index.ts:328-341`](src/siwe/index.ts#L328-L341)
+
+`new Date("garbage")` yields an Invalid Date, and any comparison involving `NaN` is `false`. As a result, a message containing `Expiration Time: not-a-date` passes `checkExpiration: true` cleanly:
+
+```ts
+const expirationDate = new Date(parsed.expirationTime); // Invalid Date
+if (expirationDate < new Date()) {                      // NaN < ... → false
+  errors.push('Message has expired');                   // never reached
+}
+```
+
+Since `validateSiweMessage` is what a server calls to decide whether to grant a session, this is the first thing to fix.
+
+**Fix:**
+- Reject the message when `expirationTime`, `notBefore`, or `issuedAt` do not parse to a valid date (`isNaN(date.getTime())`).
+- Ideally also validate RFC 3339 format in `createSiweMessage`, so a nonconforming message can't be signed in the first place.
+
+---
+
+## 2. Security hardening
+
+### 2.1 Expiration checking is opt-in and absence-tolerant
+
+`checkExpiration` defaults to off, and even when enabled it only checks if the field happens to be present. Attackers get to pick which message they replay, so lenient defaults matter here.
+
+**Fix:**
+- Check expiration and not-before **by default**; make skipping the opt-in.
+- Add a way to *require* the presence of an expiration (e.g. `requireExpiration: true`).
+
+### 2.2 Lenient parser
+
+**Location:** `parseSiweMessage` — [`src/siwe/index.ts:214-242`](src/siwe/index.ts#L214-L242)
+
+Current behavior deviates from the EIP-4361 ABNF in ways that create a gap between "what was signed / shown to the user" and "what got validated":
+
+- Fields are accepted in **any order** (spec defines a fixed order).
+- **Duplicate fields last-wins** — a message with two `Expiration Time:` lines parses to whichever comes last; another verifier may see it differently.
+- **Unknown lines are silently ignored** — arbitrary appended text is dropped from the parse but covered by the signature.
+- `parseInt("1abc", 10)` yields chain ID `1`; negative chain IDs are accepted.
+
+**Fix:** enforce field order, reject duplicate and unrecognized lines, and validate chain ID as a positive integer with no trailing garbage.
+
+### 2.3 Nonce modulo bias
+
+**Location:** `generateSiweNonce` — [`src/siwe/index.ts:59-67`](src/siwe/index.ts#L59-L67)
+
+`x % 62` over a 0–255 byte makes the first 8 characters of the alphabet appear ~25% more often (5/256 vs 4/256). Not practically exploitable at the 11-char default (~65 bits), but rejection sampling is a 3-line fix and removes the finding entirely.
+
+**Fix:** rejection sampling — discard bytes ≥ 248 (the largest multiple of 62 below 256) and draw again.
+
+### 2.4 No EIP-55 checksum enforcement
+
+The spec requires the address to be EIP-55 checksummed. `createSiweMessage` accepts anything and `parseSiweMessage` accepts any-case hex. Verification still works (comparison is lowercased), but strict third-party verifiers will reject messages w3pk produces with a lowercase address.
+
+**Fix:** normalize via `ethers.getAddress()` in `createSiweMessage`; validate checksum in `parseSiweMessage`.
+
+### 2.5 EOA-only signature verification
+
+**Location:** `verifySiweSignature` — [`src/siwe/index.ts:378-422`](src/siwe/index.ts#L378-L422)
+
+Verification only does ecrecover. EIP-4361 recommends falling back to ERC-1271 for contract accounts — and since w3pk ships an EIP-7702 module, signatures from delegated accounts are a plausible input.
+
+**Fix:** add an optional `provider` parameter enabling ERC-1271 verification (and optionally ERC-6492 for pre-deployment accounts).
+
+### 2.6 `verifySiweSignature` doesn't validate the message
+
+`valid: true` means only "signature matches the address in the message" — not that the domain, expiry, or nonce are acceptable. Integrators will misread this. [`docs/SECURITY.md:288`](docs/SECURITY.md#L288) already implies the combined check (`ethers.verifyMessage()` + message validation).
+
+**Fix:** fold `validateSiweMessage` options into `verifySiweSignature` so one call performs the full server-side check — or document sharply that both calls are required.
+
+### 2.7 Missing `scheme` field
+
+The current EIP-4361 ABNF allows an optional `scheme://` prefix on the domain line (`https://example.com wants you to sign in...`). The `SiweMessage` type, builder, and parser don't support it.
+
+**Fix:** add optional `scheme` to the interface, emit it in `createSiweMessage`, accept it in `parseSiweMessage`, and match it in `validateSiweMessage`.
+
+---
+
+## 3. DX: no high-level sign-in helper
+
+There is no one-call login flow. Users hand-assemble domain/uri/nonce/issuedAt and then call `signMessage(msg, { signingMethod: 'SIWE' })` — which is just EIP-191 under the hood ([`src/core/sdk.ts:776-781`](src/core/sdk.ts#L776-L781)).
+
+**Proposal:** a `w3pk.signInWithEthereum({ statement?, expiresIn?, resources? })` SDK method that:
+
+1. Autofills `domain` and `uri` from the current origin.
+2. Generates the nonce and `issuedAt` (plus `expirationTime` from `expiresIn`).
+3. Builds the message, signs it, and returns `{ message, signature, address }`.
+
+This turns the common login flow from five manual steps into one call.
+
+---
+
+## 4. Test coverage
+
+[`test/siwe.test.ts`](test/siwe.test.ts) is happy-path heavy. Missing negative cases to add alongside the fixes above:
+
+- Malformed `expirationTime` / `notBefore` / `issuedAt` (the §1 bug).
+- Duplicate fields and out-of-order fields.
+- Unknown/appended lines.
+- Bad chain IDs (`1abc`, negative, empty).
+- Lowercase vs checksummed addresses.
+- Domain line edge cases (embedded `" wants you to sign in..."` text).
+- Nonce distribution sanity check after the rejection-sampling fix.
+
+---
+
+## Framing notes
+
+- **Build vs depend:** an alternative to hardening the parser is depending on the maintained `siwe` npm package. Given w3pk's zero-dependency posture (dynamic `ethers` import only), hardening the in-house implementation is the consistent choice.
+- **No backward compatibility:** per project convention, change `validateSiweMessage` defaults outright (expiration checked by default) rather than adding a compat flag.
+
+## Suggested implementation order
+
+1. Datetime validation bug (§1) + strict parser (§2.2) + checksum normalization (§2.4)
+2. Safer validation defaults (§2.1) and combined verify+validate (§2.6)
+3. Nonce rejection sampling (§2.3) and `scheme` support (§2.7)
+4. ERC-1271 verification option (§2.5)
+5. `signInWithEthereum()` helper (§3)
+6. Negative-path tests (§4)

package/docs/notes/SYNCING_ACROSS_DEVICES.md

@@ -0,0 +1,127 @@
+# Syncing Across Devices
+
+How a user who registered on device A (e.g. a laptop) can use the same wallet on device B (e.g. a mobile), what currently happens, and the recommended implementation plan.
+
+**Repos involved:**
+
+- **genji-passkey** (this app) — [https://github.com/w3hc/genji-passkey](https://github.com/w3hc/genji-passkey) — local path: `/Users/ju/genji-passkey`
+- **w3pk** (the SDK) — [https://github.com/w3hc/w3pk](https://github.com/w3hc/w3pk) — local path: `/Users/ju/w3pk`
+
+Findings below are based on w3pk `v0.10.1`.
+
+---
+
+## 1. Current behavior (device A → device B)
+
+Everything is device-local. There is no server-side session or account.
+
+| Data                                                       | Where it lives                                              | Syncs across devices?                                                  |
+| ---------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Passkey (WebAuthn credential)                              | OS authenticator                                            | ✅ via iCloud Keychain / Google Password Manager (same ecosystem only) |
+| Credential metadata (username, publicKey, ethereumAddress) | Device-local storage (`/Users/ju/w3pk/src/auth/storage.ts`) | ❌                                                                     |
+| Encrypted mnemonic                                         | Browser localStorage (`w3pk_wallet_<address>`)              | ❌                                                                     |
+| Persistent session                                         | Browser localStorage (`w3pk_session_<address>`)             | ❌                                                                     |
+| Session duration setting                                   | `localStorage` (`persistentSessionDuration`)                | ❌                                                                     |
+
+**What the user experiences on device B today:**
+
+1. The app opens logged out (no persistent session on this device).
+2. Tapping **Login** fails, even when the passkey has synced. After a successful WebAuthn assertion, the SDK looks up the credential metadata in device-local storage and throws when it is missing — see `/Users/ju/w3pk/src/auth/authenticate.ts` (lines 78–86):
+   > _"Passkey authenticated but wallet data not found on this device. To sync your account: 1) Select your passkey when prompted, then 2) Provide your backup file."_
+3. In genji-passkey this message does not match `isNoPasskeyError()` in `/Users/ju/genji-passkey/src/context/W3PK.tsx`, so the user sees a raw "Authentication Failed" toast.
+4. The only working self-serve path is **Settings → Restore from Backup** (available logged out), which calls `registerWithBackupFile` — backup file + password + username → new passkey on device B, same wallet address.
+
+**Note:** the current "Device Sync" QR feature in `/Users/ju/genji-passkey/src/app/settings/page.tsx` (`handleGenerateQRCode`, ~line 1645) only shares public data (username + addresses). It does not transfer any key material and is not a wallet sync.
+
+## 2. What w3pk provides (and its gaps in v0.10.1)
+
+The SDK has a dedicated sync API that genji-passkey does not use yet:
+
+- **Device A:** `w3pk.exportForSync()` — `/Users/ju/w3pk/src/core/sdk.ts` (~line 2093). Exports a **passkey-encrypted** backup file (no password) plus a QR code when it fits (~2.9 KB limit, `/Users/ju/w3pk/src/sync/backup-sync.ts`, `generateSyncQR`).
+- **Device B:** `w3pk.syncWalletWithPasskey(backupData, password?)` — `/Users/ju/w3pk/src/core/sdk.ts` (~line 1913). Prompts passkey selection, decrypts the backup, stores the wallet, starts a session.
+
+**Gaps that prevent this from working on a fresh device:**
+
+1. **Passkey-encrypted backups cannot be decrypted on a fresh device.** The decryption key is derived from `credentialId + publicKey` (`deriveEncryptionKeyFromWebAuthn`), and the `publicKey` is only available in device-local storage. On a fresh device, `promptPasskeySelection()` returns an empty `publicKey` (`/Users/ju/w3pk/src/auth/sync-auth.ts`, lines 81–89) and the method throws. The backup file deliberately carries only a 16-char fingerprint of the key (`/Users/ju/w3pk/src/backup/backup-file.ts`, `createPasskeyBackup`) — see the security warning in §5.
+2. **Password-encrypted backups decrypt but are not persisted.** The store-wallet-and-start-session block in `syncWalletWithPasskey` is guarded by `if (credential)` from local storage (`/Users/ju/w3pk/src/core/sdk.ts`, ~line 1984) — `null` on a fresh device, so no wallet is stored and no session starts.
+3. **`importFromSync` requires being logged in first** (~line 2144), which is impossible on a fresh device (see §1, step 2) — circular.
+
+## 3. Proposed UX
+
+On device B, the register modal (in `/Users/ju/genji-passkey/src/components/Header.tsx`) gains a link:
+
+> **"I already registered on another device"**
+
+It leads to a sync flow:
+
+- **Device A** (logged in): show a QR code containing an encrypted backup of the wallet.
+- **Device B**: scan the QR with the camera, unlock, and complete setup — all on device B.
+
+Two implementation options follow. Option 1 ships now with zero SDK changes; Option 2 is the long-term passwordless path.
+
+## 4. Option 1 — QR + password (ships now, genji-passkey changes only)
+
+Device A displays a QR of a **password-encrypted** backup; device B scans it, the user types the password, and `registerWithBackupFile` creates a new passkey on device B bound to the same wallet.
+
+Works with w3pk `v0.10.1` as-is because it reuses the one path that already completes end-to-end on a fresh device.
+
+### Changes in genji-passkey (`/Users/ju/genji-passkey`)
+
+1. **`src/components/Header.tsx`** — add the "I already registered on another device" link inside the Register dialog, opening the device-B sync screen (or deep-linking to a settings section).
+2. **Device A side (new "Show sync QR" action, e.g. in `src/app/settings/page.tsx`)**:
+   - Require a fresh biometric before showing the QR (sign a throwaway message with `requireAuth: true`, or equivalent).
+   - Prompt for a password (reuse `src/components/PasswordModal.tsx`), call the existing `createBackup(password)` from `src/context/W3PK.tsx` (which wraps `w3pk.createBackupFile('password', password)`).
+   - Render a QR (reuse `qrcode.react`, already a dependency) of a payload like `{ v: 1, kind: 'w3pk-sync', username, backup: <backup file JSON> }`. Embedding the username lets device B prefill it. Size is fine: a password backup is ~600–900 bytes, under the ~2.9 KB single-QR limit.
+3. **Device B side (new sync screen reachable from the register modal)**:
+   - Add a QR **scanner** (`qrcode.react` only generates; use the native `BarcodeDetector` API with a library fallback such as `@zxing/browser`), plus a "paste JSON" fallback for devices without camera access.
+   - Parse the payload, prefill the username, prompt for the password, call the existing `registerWithBackupFile(backupJson, password, username)` from `src/context/W3PK.tsx`. This creates the passkey on device B and logs the user in.
+4. **Nice-to-have:** in the `login()` catch in `src/context/W3PK.tsx` / `Header.tsx`, detect the SDK's _"Passkey authenticated but wallet data not found"_ message and route the user to the sync screen instead of showing a raw error toast.
+
+### Changes in w3pk (`/Users/ju/w3pk`)
+
+None required.
+
+### Variant 1b — one-time code instead of a password
+
+Same architecture, but device A generates a random code, uses it as the backup password, and displays it next to the QR; the user types the code on device B instead of a real password.
+
+- Better UX than a full password on a mobile keyboard; a photographed QR alone is not enough to steal the wallet.
+- **Entropy warning:** a captured QR can be brute-forced offline, so a 6-digit code (~20 bits) is too weak even with PBKDF2 at 310k iterations. Use at least ~8 random base32 characters (~40 bits), displayed grouped (e.g. `K7QP-2MWX`).
+- Only genji-passkey changes; the code is just a generated throwaway password.
+
+## 5. Option 2 — PRF-based passwordless sync (long-term, w3pk + genji-passkey changes)
+
+Goal: device B scans the QR, passes **one biometric prompt**, and is done — no password. Safe because decryption requires possessing the platform-synced passkey, not just the QR.
+
+Uses the WebAuthn **PRF extension**: the authenticator derives a secret from `PRF(salt)` that never leaves the authenticator boundary, and **syncs with the passkey** for platform credentials. Support: Chrome 108+, Safari 17+/iOS 17+; not Firefox. Same-ecosystem only (iCloud↔iCloud, Google↔Google) — keep Option 1 as the cross-ecosystem fallback.
+
+> **Why not just embed the `publicKey` in the passkey-encrypted backup to fix gap §2.1?** Because the current key is _deterministically derived from `credentialId + publicKey`_ — a file containing the ciphertext plus both inputs would be **self-decrypting**: anyone holding it gets the mnemonic with no hardware or biometric. That is exactly why only a fingerprint is stored today. PRF is the correct fix.
+
+### Changes in w3pk (`/Users/ju/w3pk`)
+
+1. **`src/wallet/crypto.ts`** — extend key derivation with a PRF path: request the `prf` extension in `navigator.credentials.get()` (and `create()` during registration), derive the AES key as `HKDF(prfOutput, salt)`. (Groundwork partially exists per `docs/SECURITY.md` — `deriveEncryptionKeyFromWebAuthn` / auto-fallback notes.)
+2. **`src/backup/backup-file.ts` + `src/backup/types.ts`** — new `encryptionMethod: 'prf'`: payload `{ ciphertext, prfSalt, credentialId, addressChecksum, username }`. No `publicKey` and no fingerprint needed; the QR alone is useless without the synced passkey + biometric.
+3. **`src/core/sdk.ts` — `exportForSync()`** (~line 2093) — when PRF is available, perform a fresh assertion with PRF evaluation and emit a `'prf'` backup; otherwise fall back to a password backup.
+4. **`src/core/sdk.ts` — `syncWalletWithPasskey()`** (~line 1913) — handle `'prf'` backups: call `navigator.credentials.get()` with `allowCredentials: [credentialId from payload]` and PRF eval using `prfSalt`; derive the key, decrypt, verify `addressChecksum`.
+5. **Fix the fresh-device persistence gap** (~line 1984): when the credential is not in local `CredentialStorage`, still (a) bootstrap credential metadata from the sync payload (username, credentialId; store the wallet under a PRF-derived local key rather than the `publicKey`-based one), (b) store the wallet, (c) start the session and fire `onAuthStateChanged`.
+6. **`src/auth/authenticate.ts`** (lines 78–86) — replace the string-only dead end with a **typed error** (e.g. `SyncRequiredError` carrying the `credentialId`) so apps can catch it and launch their sync flow.
+7. **`src/sync/backup-sync.ts`** — `generateSyncQR` / `parseSyncQR` gain the `'prf'` payload shape; `importFromSync` should no longer require an existing login (uses the same bootstrap as #5).
+
+### Changes in genji-passkey (`/Users/ju/genji-passkey`)
+
+1. Same UI as Option 1 (register-modal link, device A QR screen, device B scanner).
+2. **Device A:** call `w3pk.exportForSync()` instead of `createBackup(password)`; only fall back to the password QR when PRF is unavailable.
+3. **Device B:** call `w3pk.syncWalletWithPasskey(scannedPayload)` — one biometric prompt, no password. Offer "Use a password instead" for cross-ecosystem or non-PRF browsers (Option 1 path).
+4. Catch the new typed `SyncRequiredError` from `login()` in `src/context/W3PK.tsx` and route to the sync screen.
+
+## 6. Security considerations
+
+- **A QR code is an exportable artifact.** A fully self-contained passwordless QR would be the mnemonic on a screen: screenshots, screen sharing, or a camera over the shoulder leak it, and client-side TTLs are unenforceable (an attacker decrypts a captured QR at leisure). Something must exist **outside** the QR: the password (Option 1), a one-time code (Variant 1b), or the synced passkey + biometric (Option 2).
+- **Gate QR display on device A behind a fresh biometric** in every variant. This protects against a stolen unlocked laptop — not against QR capture.
+- **"User is logged in on device A" is not sufficient justification for a self-decrypting QR** — the threat is not the user, it's anyone who can photograph or intercept the artifact.
+- Short numeric codes are brute-forceable offline once the QR is captured; see the entropy warning in Variant 1b.
+
+## 7. Recommendation
+
+1. **Ship Option 1 now** — zero SDK changes, reuses `registerWithBackupFile`, `PasswordModal`, and `qrcode.react`. Upgrade to Variant 1b if password-typing friction matters.
+2. **Pursue Option 2 in w3pk** as the passwordless same-ecosystem path — it also properly fixes the currently dead-ended `syncWalletWithPasskey` / `importFromSync` APIs — and keep the password/code QR as the cross-ecosystem fallback.

package/docs/notes/ethereum-post-quantum-roadmap.md

@@ -0,0 +1,213 @@
+---
+title: "Ethereum's post-quantum roadmap: technical details"
+description: How Ethereum plans to replace BLS, ECDSA and KZG with hash-based and lattice primitives, with the parameters, sizes and fork milestones as they stand in September 2026.
+date: 2026-09-13
+locale: en_US
+author: Julien Béranger
+model: Claude Opus 5
+conversation: https://claude.ai/chat/<CONVERSATION_ID>
+---
+
+## The shape of the problem
+
+[Ethereum](https://ethereum.org/) depends on four families of public-key cryptography that
+[Shor's algorithm](https://en.wikipedia.org/wiki/Shor%27s_algorithm) breaks:
+[ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) on secp256k1 for
+account signatures, [BLS signatures](https://en.wikipedia.org/wiki/BLS_digital_signature) for validator
+attestations, KZG polynomial commitments for
+[blob data availability](https://eips.ethereum.org/EIPS/eip-4844), and pairing-based SNARKs at the
+application layer. The [Ethereum Foundation](https://ethereum.foundation/)'s
+[Post-Quantum team](https://pq.ethereum.org/) frames the realistic failure mode as stolen funds and
+impersonation rather than rewriting finalized history — past transactions and finalized blocks stay
+valid regardless.
+
+The answer is the [lean Ethereum](https://blog.ethereum.org/2025/07/31/lean-ethereum) programme,
+published by [Justin Drake](https://x.com/drakefjustin) on 31 July 2025, which makes the hash function
+the single cryptographic primitive across consensus, data and execution. A dedicated EF Post-Quantum
+team formed in January 2026 under Thomas Coratger. The official target is roughly **2029** for core L1
+infrastructure, with full execution-layer and ecosystem migration extending past that.
+
+## Consensus layer: leanXMSS
+
+Validator keys move from BLS12-381 to **leanXMSS**, a variant of the
+[eXtended Merkle Signature Scheme](https://en.wikipedia.org/wiki/Hash-based_cryptography) built from
+one-time hash-based signatures organised in [Merkle trees](https://en.wikipedia.org/wiki/Merkle_tree).
+The construction and its security analysis are set out in
+[Hash-Based Multi-Signatures for Post-Quantum Ethereum](https://eprint.iacr.org/2025/055.pdf).
+
+| Property | BLS12-381 | leanXMSS |
+| --- | --- | --- |
+| Public key | 48 bytes | 52-byte Merkle root + 20-byte public parameter |
+| Signature | 96 bytes | 3,112 bytes |
+| Aggregation | native, algebraic | none — requires SNARK |
+| Key lifetime | unbounded | 2^32 slots (~1,632 years at 12s slots) |
+
+Registering roughly one million validators expands consensus state by about 52 MiB. Each key derives
+from a single 32-byte master seed.
+
+[EIP-8310](https://eips.ethereum.org/EIPS/eip-8310) defines the keystore format for these stateful
+keys. Its recommended production parameter set matches the
+[leanSig](https://github.com/leanEthereum/leanSig) instantiation
+`SIGAbortingTargetSumLifetime32Dim46Base8`:
+
+```json
+{
+  "name": "leanxmss",
+  "params": {
+    "hash": "<hash identifier>",
+    "tree_height": 32,
+    "hypertree_layers": 1,
+    "encoding": "target_sum",
+    "winternitz_w": 8,
+    "dimension": 46,
+    "target_sum": 200,
+    "index_mode": "synchronized",
+    "activation_epoch": 0,
+    "lifetime_leaves": 4294967296
+  }
+}
+```
+
+The format is deliberately hash-agnostic: the concrete hash lives in the `hash` field, and a reader that
+does not recognise `scheme.name` must refuse to use the keystore.
+
+## Aggregation: leanVM
+
+Hash-based signatures have no algebraic aggregation, so lean Ethereum replaces group operations with a
+succinct argument — an aggregate becomes a proof that many valid signatures exist, with the verification
+logic compiled into a circuit. **leanVM** is the minimal, [Cairo](https://www.cairo-lang.org/)-inspired
+zkVM that does this, producing one SNARK per slot. The reference implementations live in
+[leanMultisig](https://github.com/leanEthereum/leanMultisig), with an executable
+[Python](https://www.python.org/) specification in [leanSpec](https://github.com/leanEthereum/leanSpec)
+used by around ten client teams.
+
+Benchmarks on an M4 Max put leanVM at roughly 1,000 XMSS verifications per second with recursive proofs
+under one second. The stated compression target is 250x, which is what keeps 3 KB signatures from
+blowing up per-slot bandwidth.
+
+## The open hash and field question
+
+This is the least settled part of the design. Poseidon2, long the default SNARK-friendly choice, is
+under cryptanalytic pressure from recent attacks on algebraic hashes — not broken, but not yet worth
+betting a century of consensus on. The team has floated registering validators under several hash
+functions up front ([Poseidon](https://eprint.iacr.org/2019/458),
+[BLAKE3](https://github.com/BLAKE3-team/BLAKE3),
+[SHA-3](https://en.wikipedia.org/wiki/SHA-3)) purely to preserve agility. The finite-field choice
+between KoalaBear and Goldilocks is also live, the latter offering more proof-size headroom at roughly
+2x slower proving.
+
+The tradeoff moved in 2026. Benchmarks on a single M4 Max core put BLAKE3's compression function at
+roughly 82,000 proofs per second, [SHA-256](https://en.wikipedia.org/wiki/SHA-2) at about 42,000 and
+[Keccak](https://en.wikipedia.org/wiki/SHA-3) at around 30,000; across ten cores BLAKE3 exceeded 660,000.
+Hash-friendly SNARKs have reduced the need for SNARK-friendly hashes, so conventional, heavily analysed
+hashes can now enter the design without their former proving penalty.
+
+## Execution layer: EIP-8141 frame transactions
+
+[EIP-8141](https://eips.ethereum.org/EIPS/eip-8141) introduces a new
+[EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) transaction type (`0x06`) that decomposes a
+transaction into a sequence of **frames** — contract calls that validate the transaction, approve gas
+payment, and execute user operations. A new `APPROVE` opcode moves signature checking and gas payment
+out of rigid protocol rules and into the [EVM](https://ethereum.org/developers/docs/evm/). It builds on
+[EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) and supersedes much of what
+[ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) does with off-chain bundlers.
+
+The post-quantum relevance is cryptographic agility: an account defines its own validation logic, so a
+wallet can adopt a post-quantum scheme on its own schedule without a network-wide flag day and without
+a dedicated hard fork per scheme.
+
+Mempool safety is specified rather than assumed. Validation work per transaction is bounded by
+`MAX_VERIFY_GAS`, clients normally admit at most one pending frame transaction per sender, and
+validation dependencies are tracked so only affected transactions are revalidated after a new canonical
+block. Failure of a `VERIFY` frame invalidates the whole transaction rather than merely halting a call
+frame. [MATCHA](https://ethresear.ch/t/mempool-account-transaction-capacity-from-historical-activity-matcha/25949)
+proposes relaxing the one-per-sender rule for accounts using
+[EIP-8250](https://eips.ethereum.org/EIPS/eip-8250) keyed nonces.
+
+A cluster of proposals extends the frame model:
+[EIP-8272](https://eips.ethereum.org/EIPS/eip-8272) for recent roots,
+[EIP-8209](https://eips.ethereum.org/EIPS/eip-8209) for commit/reveal frames, and
+[ERC-8286](https://eips.ethereum.org/EIPS/eip-8286) binding frame validation to
+[ERC-7579](https://eips.ethereum.org/EIPS/eip-7579) modular accounts.
+
+## Precompiles
+
+The J\* milestone favours a **vector math precompile** — modular primitives such as
+[EIP-7885](https://eips.ethereum.org/EIPS/eip-7885) for number-theoretic transform operations — over
+whole-scheme verifiers, on the grounds that it avoids locking the protocol to a scheme that later falls
+to cryptanalysis.
+
+Whole-scheme drafts exist regardless. [EIP-8051](https://eips.ethereum.org/EIPS/eip-8051) specifies
+`VERIFY_MLDSA` (compliant with [FIPS 204](https://www.nist.gov/news-events/news/2024/08/nist-releases-first-3-finalized-post-quantum-encryption-standards))
+alongside a cheaper `VERIFY_MLDSA_ETH` that swaps SHAKE256 for a Keccak-based PRNG and stores the
+public-key polynomial `t1` in the NTT domain to skip one transform during verification.
+[EIP-8355](https://eips.ethereum.org/EIPS/eip-8355) extends ML-DSA coverage to NIST security levels III
+and V. Older [Falcon](https://eips.ethereum.org/EIPS/eip-7619) proposals remain on the table; at 1,681
+bytes per signature and 16 gas per non-zero calldata byte, a bare Falcon signature costs about 26,896
+gas just to carry.
+
+## Data layer
+
+KZG commitments inherit the same pairing weakness. The current mitigation is structural rather than
+cryptographic: the trusted setup holds as long as one participant discarded their secret, and that
+remains true against a quantum adversary working after the fact. The replacements under study are
+[STARK](https://eprint.iacr.org/2018/046)-style hash-based commitments and lattice-based commitments,
+neither yet efficient enough at Ethereum's scale.
+
+## Fork milestones
+
+The [EF Protocol Architecture](https://strawmap.org/) roadmap places post-quantum work across all three
+layers. These are planning milestones, not commitments — names and ordering may change.
+
+| Fork | Milestone | Layer |
+| --- | --- | --- |
+| I\* | PQ key registry | Consensus |
+| J\* | PQ signature precompiles | Execution |
+| L\* | PQ attestations, real-time CL proofs, leanVM | Consensus + Data |
+| M\* | PQ signature aggregation, PQ blobs | Execution + Data |
+| Longer term | Full PQ consensus, PQ transactions, PQ sampling | All layers |
+
+The nearest real fork is **Hegotá**, targeted for 2027 after
+[Glamsterdam](https://ethereum.org/roadmap/). It is not itself a post-quantum fork; it is the gate that
+decides whether the later PQ forks land on time. The EF's Protocol cluster reviewed 62 candidate EIPs
+with 397 grades from nine client teams and named exactly two must-ship:
+[EIP-7805](https://eips.ethereum.org/EIPS/eip-7805) (FOCIL) and EIP-8141. If either hits technical
+friction, the schedule shifts rather than the proposal being cut. Five further forks follow, averaging
+one every 7.2 months, which forces overlapping rather than sequential execution — a pace Ethereum has
+not previously sustained. A "minimum viable post-quantum" fallback exists for a sudden breakthrough.
+
+## Threat model and residual exposure
+
+The EF's own ordering of risk surfaces: user accounts first (largest pool of value, public keys exposed
+after the first transaction), then high-value operational keys at exchanges and bridges, then governance
+multisigs, then validator keys — which affect consensus participation rather than directly holding
+assets.
+
+"Harvest now, decrypt later" is largely a confidentiality problem, not an ownership one: recording
+transactions today does not enable retroactive theft, since blockchains are integrity systems built on
+signatures. The forward-looking risk is that exposed public keys become derivable once a
+cryptographically relevant machine exists.
+
+Dormant funds are the governance question nobody has answered. The EF estimates Ethereum's long-dormant
+exposure at roughly 0.1% of supply, against about 5% for [Bitcoin](https://bitcoin.org/) in early
+address formats. That gap is what makes "do nothing" a more defensible option for Ethereum than it would
+be for Bitcoin.
+
+On timing, the EF team is more conservative than the headlines: most engineering roadmaps place
+cryptographic relevance in the early-to-mid 2030s. [Google Quantum AI](https://quantumai.google/)'s
+March 2026 [analysis](https://research.google/blog/safeguarding-cryptocurrency-by-disclosing-quantum-vulnerabilities-responsibly/)
+lowered the estimate for breaking 256-bit elliptic curve cryptography to roughly 1,200 logical qubits,
+and [NIST](https://csrc.nist.gov/projects/post-quantum-cryptography) anticipates deprecating ECDSA by
+2030 and disallowing it by 2035. Verification runs in parallel: the EF's Protocol Snarkification team
+under Alex Hicks is running a $20M, three-year zkEVM formal verification project covering the SNARK
+primitives beneath PQ aggregation.
+
+## Further reading
+
+- [pq.ethereum.org](https://pq.ethereum.org/) — EF Post-Quantum team, roadmap and FAQ
+- [Post-quantum cryptography on Ethereum](https://ethereum.org/roadmap/security/quantum-resistance/) — ethereum.org
+- [leanEthereum GitHub organisation](https://github.com/leanEthereum)
+- [lean consensus roadmap](https://leanroadmap.org/) and [strawmap.org](https://strawmap.org/)
+- [Securing Elliptic Curve Cryptocurrencies Against Quantum](https://quantumai.google/static/site-assets/downloads/cryptocurrency-whitepaper.pdf) — Google × EF
+- [EIP-8141 implementation tracker](https://github.com/ethereum/execution-specs/issues/2829)
+- [EIP-8141 discussion](https://ethereum-magicians.org/t/eip-8141-frame-transaction/27617) — Fellowship of Ethereum Magicians

package/docs/notes/wulong-building-finding.md

@@ -0,0 +1,109 @@
+---
+title: What w3pk needs for SIWE login on Wulong
+description: Changes w3pk needs so a UI can sign in to Wulong with SIWE, found while hardening Wulong's SIWE verification.
+date: 2026-09-29
+locale: en_US
+author: Julien Béranger
+model: Claude Opus 5.5
+---
+
+## Context
+
+[Wulong](https://github.com/w3hc/wulong) is hardening its [SIWE](https://eips.ethereum.org/EIPS/eip-4361) verification in [issue #23](https://github.com/w3hc/wulong/issues/23). Once it lands, Wulong verifies every sign-in with the [siwe](https://github.com/spruceid/siwe) library (v3.0.0) and enforces:
+
+- **Domain:** the message's `domain` must be one Wulong is configured to accept, which is the UI's host (with its port).
+- **Nonce:** it must be one Wulong issued through `POST /auth/nonce`, tied to the address that signs. It is used up on the first attempt and lasts 5 minutes.
+- **Time:** `Issued At` must fall between when the nonce was issued and now. siwe also enforces `Expiration Time` and `Not Before`.
+
+A UI built on w3pk should be able to sign in against these rules. One bug blocks that, and one point needs checking.
+
+## 1. Fix `createSiweMessage` when there is no statement
+
+**Bug.** [`createSiweMessage`](src/siwe/index.ts#L90) writes one blank line between the address and `URI:` when `statement` is omitted. [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361#message-format) requires two, and the blank line after the statement slot is always there. siwe v3's parser rejects the w3pk output.
+
+Tested against siwe 3.0.0:
+
+| Message | Result |
+| --- | --- |
+| w3pk, no statement | rejected: `invalid message: max line number was 7` |
+| w3pk, with statement | accepted |
+| siwe's own format, no statement | accepted |
+
+Until this is fixed, a w3pk UI can sign in to Wulong (or any other server using siwe) only if it passes a `statement`.
+
+**Fix.** Always write the blank line that follows the statement slot:
+
+```ts
+message += `${params.address}\n`;
+message += `\n`;
+if (params.statement) {
+  message += `${params.statement}\n`;
+}
+message += `\n`;
+```
+
+w3pk's [`parseSiweMessage`](src/siwe/index.ts) already reads this format: an empty line where the statement would be is skipped.
+
+**Done when.**
+
+- A message built without a statement is byte-identical to the output of `new SiweMessage({...}).prepareMessage()` for the same fields.
+- `test/siwe.test.ts` covers this with a test that builds a message with and without a statement, parses each with siwe and gets it back unchanged. That needs siwe as a dev dependency.
+
+## 2. Check SIWE signing in PRIMARY mode
+
+**Not verified yet.** [`getAddress('PRIMARY')`](src/core/sdk.ts#L590) returns the address derived from the passkey's [P-256](https://eips.ethereum.org/EIPS/eip-7951) public key. [`signMessage`](src/core/sdk.ts#L731), however, always signs with a key derived from the mnemonic through `getOriginSpecificAddress`, whatever the mode. A SIWE message built with the PRIMARY address and signed with `signMessage(..., { mode: 'PRIMARY', signingMethod: 'SIWE' })` would then carry a signature that does not recover to the address in the message. Wulong, and any server using siwe, would reject it.
+
+A P-256 [WebAuthn](https://www.w3.org/TR/webauthn-3/) signature, as `signMessageWithPasskey` produces, isn't a plain [EIP-191](https://eips.ethereum.org/EIPS/eip-191) signature from an externally owned account either. siwe can't verify it without an [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271) contract on chain.
+
+**Done when**, either way:
+
+- `signMessage` rejects `mode: 'PRIMARY'` with `signingMethod: 'SIWE'` with a clear error, and the docs say SIWE needs STANDARD, STRICT or YOLO; or
+- a test shows that a PRIMARY-mode SIWE signature recovers to `getAddress('PRIMARY')`.
+
+## 3. Show the server nonce flow in the SIWE example
+
+[`examples/siwe-login.ts`](examples/siwe-login.ts) makes the nonce with `generateSiweNonce()` on the client. Wulong issues nonces on the server and ties each to an address, which is also what EIP-4361 recommends. An example of the flow Wulong expects would help UI builders:
+
+```ts
+const address = await w3pk.getAddress('STANDARD');
+
+const { nonce } = await fetch(`${WULONG_URL}/auth/nonce`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ address }),
+}).then((r) => r.json());
+
+const message = createSiweMessage({
+  domain: window.location.host,
+  address,
+  uri: window.location.origin,
+  version: '1',
+  chainId: 1,
+  nonce,
+  issuedAt: new Date().toISOString(),
+});
+
+const { signature } = await w3pk.signMessage(message, {
+  mode: 'STANDARD',
+  signingMethod: 'SIWE',
+});
+
+await fetch(`${WULONG_URL}/chest/access/${slot}`, {
+  headers: {
+    'x-siwe-message': btoa(message),
+    'x-siwe-signature': signature,
+  },
+});
+```
+
+Points to document next to it:
+
+- **Same mode and tag.** Call `getAddress` with the same mode and tag you'll sign with. Addresses are derived per origin, so the address the nonce is tied to must be the one that signs.
+- **`domain`.** Use `window.location.host`, which includes the port. Wulong must list that host in `SIWE_DOMAIN`.
+- **Time limit.** Sign within 5 minutes of getting the nonce. A longer `expirationTime` in the message is allowed, but Wulong still stops accepting the nonce after 5 minutes.
+
+## Further reading
+
+- [EIP-4361: Sign-In with Ethereum](https://eips.ethereum.org/EIPS/eip-4361)
+- [siwe library](https://github.com/spruceid/siwe)
+- [EIP-55: mixed-case checksum address encoding](https://eips.ethereum.org/EIPS/eip-55) (siwe requires checksummed addresses; w3pk's [ethers](https://docs.ethers.org/v6/) wallets already produce them)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w3pk",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "WebAuthn SDK for passwordless authentication, encrypted wallets, ERC-5564 stealth addresses, and zero-knowledge proofs",
   "author": "Julien Béranger",
   "license": "GPL-3.0",
@@ -87,6 +87,7 @@
     "@types/node": "^25.9.2",
     "@types/qrcode": "^1.5.5",
     "circomlib": "^2.0.5",
+    "siwe": "3.0.0",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"
@@ -111,7 +112,7 @@
     "build:zk": "npm run build && npm run compile:circuits",
     "compile:circuits": "node scripts/compile-circuits.js",
     "dev": "tsup --watch",
-    "test": "tsx test/test.ts && tsx test/comprehensive.test.ts && tsx test/backup.test.ts && tsx test/social-recovery.test.ts && tsx test/recovery-education.test.ts && tsx test/zk/zk.test.ts && tsx test/nft-ownership.test.ts && tsx test/chainlist.test.ts && tsx test/eip7702.test.ts && tsx test/external-wallet.test.ts && tsx test/erc5564.test.ts && tsx test/zk/key-stretching.test.ts && tsx test/username-encoding.test.ts && tsx test/username-validation.test.ts && tsx test/origin-derivation.test.ts && tsx test/build-hash.test.ts && tsx test/credential-checking.test.ts && tsx test/webauthn-native.test.ts && tsx test/persistent-session.test.ts && tsx test/sign-message.test.ts && tsx test/siwe.test.ts && tsx test/requirereauth.test.ts && tsx test/eip7951.test.ts && tsx test/send-transaction.test.ts && tsx test/eip1193-provider.test.ts && tsx test/mlkem.test.ts",
+    "test": "tsx test/test.ts && tsx test/comprehensive.test.ts && tsx test/backup.test.ts && tsx test/social-recovery.test.ts && tsx test/recovery-education.test.ts && tsx test/zk/zk.test.ts && tsx test/nft-ownership.test.ts && tsx test/chainlist.test.ts && tsx test/eip7702.test.ts && tsx test/external-wallet.test.ts && tsx test/erc5564.test.ts && tsx test/zk/key-stretching.test.ts && tsx test/username-encoding.test.ts && tsx test/username-validation.test.ts && tsx test/origin-derivation.test.ts && tsx test/build-hash.test.ts && tsx test/credential-checking.test.ts && tsx test/webauthn-native.test.ts && tsx test/persistent-session.test.ts && tsx test/local-storage.test.ts && tsx test/sign-message.test.ts && tsx test/siwe.test.ts && tsx test/requirereauth.test.ts && tsx test/eip7951.test.ts && tsx test/send-transaction.test.ts && tsx test/eip1193-provider.test.ts && tsx test/mlkem.test.ts && tsx test/login-missing-wallet.test.ts && tsx test/backup-status.test.ts",
     "test:basic": "tsx test/test.ts",
     "test:comprehensive": "tsx test/comprehensive.test.ts",
     "test:backup": "tsx test/backup.test.ts",