w3pk 0.10.2 → 0.10.4

package/docs/notes/IFRAME_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,197 @@
+# w3pk — Cross-Origin Iframe Wallet Implementation Plan
+
+**Goal:** Remove all key material from the host app's JS realm. Host apps send payloads over postMessage; the wallet origin signs — or refuses, based on per-app policy. No onchain contracts, no gas, works on every chain. A companion browser extension (Phase 2) adds AI-powered explanation of what apps request.
+
+**Threat model addressed:** Malicious or XSS-compromised host apps. Out of scope: compromised wallet origin, compromised device/OS, malicious browser extensions with full page access.
+
+**Security claim (for SECURITY.md):** *Host compromise cannot extract keys; damage is bounded by the app's active grant and the balance of its app-specific address.* (Not: "prevents XSS.")
+
+---
+
+# Phase 1 — Iframe Wallet with Iframe-Enforced Policy
+
+## 1. Architecture
+
+```
+┌─────────────────────────────┐        ┌──────────────────────────────┐
+│  Host app (any origin)      │        │  wallet.w3pk.w3hc.org (iframe)    │
+│                             │        │                              │
+│  w3pk SDK (thin client)     │◄──────►│  Key vault (mnemonic, HD     │
+│  - postMessage RPC          │  post  │  derivation, signing)        │
+│  - EIP-1193 provider shim   │ Message│  Policy engine               │
+│  - no key material, ever    │        │  Session manager             │
+└─────────────────────────────┘        │  WebAuthn (RP ID = wallet…w3hc.org) │
+                                       └──────────┬───────────────────┘
+                                                  │ window.open (same origin)
+                                       ┌──────────▼───────────────────┐
+                                       │  Confirmation popup           │
+                                       │  tx decoding + simulation     │
+                                       │  grant display & approval     │
+                                       │  biometric re-auth            │
+                                       └──────────────────────────────┘
+```
+
+Three deliverables:
+
+1. **`w3pk` SDK (host side)** — becomes a thin RPC client. Public API unchanged where possible (`register`, `login`, `signMessage`, `sendTransaction`, `getEIP1193Provider`, `deriveWallet` minus key export).
+2. **Wallet origin app (`wallet.w3pk.w3hc.org`)** — static, minimal-dependency page loaded in a hidden iframe. Owns WebAuthn credentials, mnemonic encryption/decryption, HD derivation, signing, sessions, and the policy engine.
+3. **Confirmation popup** — same wallet origin, opened via `window.open` for grant approval and per-signature confirmation. A separate window cannot be overlaid or clickjacked by the host.
+
+Only requests and signatures cross the postMessage boundary. Private keys — master or derived — never do, in any mode.
+
+## 2. Security modes
+
+| Mode | Address | User interaction | Enforcement |
+|---|---|---|---|
+| **PRIMARY** | P-256 passkey address (EIP-7951) | Biometric prompt on **every** signature | Hardware — every P-256 signature *is* a WebAuthn ceremony; the key physically cannot sign without the user. Strongest tier by construction. Limited to signatures / EIP-7951-capable flows (no plain EOA txs). |
+| **STRICT** | STRICT-derived address | Confirmation popup + fresh biometric on **every** signature | Policy engine forces `confirm` classification for all requests. No persistent session. |
+| **STANDARD** | STANDARD-derived address (per origin/tag) | User reviews and **approves the grant** (the JSON below) once at connect, in the popup. Within the grant: silent. Outside or above thresholds: escalates to popup. | Policy engine enforces the approved grant on every request. |
+| **YOLO** | Tag-derived address | Grant approval once; then signs generously (high cap, broad silent list) | Same engine, permissive preset. **Key still never leaves the iframe** — YOLO is a policy, not key export. Backstopped by app-budget funding. |
+
+Key mode principles:
+
+- **STANDARD's consent moment is the grant, not each transaction.** The popup renders the grant human-readably (allowed contracts, spend cap, expiry, silent vs. confirm actions) and the user approves it with a biometric. Everything the grant covers is then silent; everything else escalates. Editing/renewing a grant re-runs the same approval.
+- **PRIMARY and STRICT differ in *what* signs, not *how often* the user is asked:** PRIMARY's prompt is the P-256 hardware ceremony itself; STRICT's is the policy engine refusing to sign with the derived secp256k1 key without a fresh confirmation.
+- **YOLO's worst case = its grant ∩ its address balance.** Surface app-specific addresses as "app budgets" in UX: fund the GAMING address with 0.1 ETH and that is the physical maximum loss, independent of the policy engine.
+
+## 3. Milestones
+
+### M1 — Wallet origin skeleton + transport
+
+- **Naming decision (permanent):** wallet origin = `wallet.w3pk.w3hc.org`, RP ID = `wallet.w3pk.w3hc.org`, break-glass mirror = `recovery.wallet.w3pk.w3hc.org`. RP ID scoping consequences: the recovery mirror (child of the RP ID) can perform the passkey ceremony; the demo app at `w3pk.w3hc.org` (parent) cannot — it is a plain untrusted host app like any other. The RP ID and origin-scoped storage bind users to this hostname permanently; the `w3hc.org` zone must be governed accordingly (see M5 Availability). A later move to a standalone domain would require a per-user re-registration ceremony.
+- Ship `wallet.w3pk.w3hc.org` as a static bundle: strict CSP, SRI, no third-party scripts, no analytics, near-zero dependencies.
+- postMessage RPC layer:
+  - Handshake with capability exchange and protocol version.
+  - Every message validated against a JSON schema; strict `event.origin` checks on both sides; per-request nonces; responses via `MessageChannel` ports (not broadcast).
+  - **App identity = transport-level `event.origin`.** Never trust an origin claimed inside the payload.
+- SDK refactor: replace in-realm crypto calls with RPC calls. Feature-flag so the legacy in-realm mode remains available during migration.
+
+### M2 — Key custody migration
+
+- Move WebAuthn registration/login into the wallet origin. RP ID = `wallet.w3pk.w3hc.org` → host apps can no longer trigger the credential ceremony at all.
+- Use the WebAuthn **PRF extension** (where available) to derive the mnemonic encryption key from the authenticator; fall back to the current encryption scheme otherwise. Decryption happens only in the wallet origin.
+- HD derivation (origin/tag → app-specific keys) and EIP-7951 P-256 signing move into the wallet origin. Derived keys never cross postMessage.
+- **Remove key export from the cross-origin API.** `exportMnemonic()` and YOLO key return are not representable in the protocol.
+- Migration path for existing users: one-time flow that re-registers the credential under the wallet RP ID and re-encrypts the backup. `restoreFromBackupFile` keeps working, in the wallet origin.
+
+### M3 — Policy engine + grant approval flow
+
+- Grant schema, stored per `(appOrigin, tag)` in the wallet origin (IndexedDB, encrypted at rest):
+
+```json
+{
+  "version": 1,
+  "appOrigin": "https://game.example.com",
+  "tag": "GAMING",
+  "mode": "STANDARD",
+  "chains": [1, 10, 8453],
+  "expiry": "2026-07-19T00:00:00Z",
+  "spend": { "capWei": "100000000000000000", "windowHours": 24 },
+  "allowedContracts": [
+    { "address": "0xabc...", "selectors": ["0xa9059cbb"] }
+  ],
+  "silent": ["personal_sign", "eth_signTypedData_v4:whitelisted"],
+  "confirm": ["eth_sendTransaction:aboveCap", "approve", "permit"],
+  "forbid": ["eth_sign_rawHash:unlessTagged"]
+}
+```
+
+  `allowedContracts` is a whitelist of existing third-party contracts the app may call — data the engine checks, nothing to deploy.
+
+- **Grant approval flow (the STANDARD consent moment):** at first connect, the app proposes a grant; the popup renders it human-readably; the user approves with a biometric. Stored grants are renewable, editable, and revocable from a wallet-origin management screen. Expiry enforced by the engine.
+- Enforcement pipeline on every signing request: `parse → match grant → decode calldata → classify (silent / confirm / deny) → sign or escalate`.
+- Hard rules baked in regardless of grant or mode: `approve`/`permit`/`Permit2` and raw-hash signing always require confirmation; unlimited approvals rewritten or denied by default.
+- Mode presets implemented as grant templates: STRICT = all-confirm + no persistence; YOLO = permissive; PRIMARY = routes to P-256 signing (inherently per-signature ceremony).
+
+### M4 — Confirmation popup (trusted UI)
+
+- Same wallet origin, opened with `window.open`. Two jobs:
+  1. **Grant approval** — render the proposed grant: which app, which contracts, spend cap, expiry, what will be silent vs. confirmed.
+  2. **Per-signature confirmation** — decoded calldata (bundled/self-hosted ABI + 4byte registry), simulated balance diffs, target contract, requesting origin, and which grant rule triggered escalation.
+- Fresh WebAuthn assertion for approvals and high-tier actions.
+- Popup-blocked fallback: full-page redirect flow with return URL.
+- **Must be safe standalone** — the Phase 2 extension enhances comprehension but is never required for safety.
+
+### M5 — Hardening + release
+
+- Wallet origin: CSP report-only → enforce; `Cross-Origin-Opener-Policy`; deliberate frame-ancestors decision (allow embedding, bind identity to embedder origin).
+- Extend the existing IPFS build-verification + onchain registry to the deployed wallet-origin bundle, not just the npm package.
+- Test suite: hostile-host fixture attempting key extraction and policy bypass; policy engine property tests; replay/nonce tests on the RPC layer.
+- Docs: update SECURITY.md with the bounded-damage claim above; explicitly state that workers/service workers are not a security *boundary* (they are used for availability, below).
+
+#### Availability (the wallet origin as shared dependency)
+
+The wallet is a static bundle on CDN-class hosting — no backend, no database, no server-side key handling. The encrypted mnemonic lives in the user's browser storage, so an outage never touches keys, funds, or sessions in progress. The remaining risk is sized and mitigated as follows:
+
+- **Service worker in the wallet origin (availability, not security):** after first load, the wallet bundle serves from the user's own cache. Returning users keep authenticating and signing through an origin outage; only first-time users on a new device are affected.
+- **Offline recovery is origin-independent:** the `standalone/` recovery tool + encrypted backup files + social recovery restore the mnemonic without any w3pk infrastructure. **Availability failure ≠ custody failure** — state this verbatim in SECURITY.md.
+- **Break-glass mirror (later, optional):** RP ID = `wallet.w3pk.w3hc.org` means any subdomain of it can perform the passkey ceremony. A pre-published `recovery.wallet.w3pk.w3hc.org` on separate infrastructure lets users restore from a backup file even if the primary is dark (origin storage does not transfer, so this is a recovery path, not a hot mirror — which is all break-glass needs to be).
+- **Domain governance is the real SPOF, not uptime:** the RP ID and origin-scoped storage bind users to the domain permanently. Registrar lock + 2FA, DNSSEC, long-term renewal, deploy credentials treated like a private key. Domain loss/hijack is the catastrophic scenario; CDN downtime is minutes per year.
+
+Accurate availability claim: *during a wallet-origin outage, new users cannot onboard; existing users are unaffected; funds are never locked under any scenario.*
+
+#### Verifiability (trusting the wallet origin without taking its word)
+
+The wallet origin is the trusted computing base — it decrypts the mnemonic. The architecture does not remove that trust; it consolidates it (from "every host app, forever" to "one small static codebase") and then makes it verifiable in layers:
+
+1. **Auditable source:** the wallet-origin app is open source, like the SDK. Necessary, not sufficient.
+2. **Reproducible builds:** deterministic build pipeline — anyone can build a tagged release and get byte-identical output whose IPFS CID matches the onchain registry entry. The published artifact is provably derived from the audited source.
+3. **Served-bytes verification (the hard part):** a server can serve *different* code to a targeted user — the classic weakness of web-delivered crypto that no repo audit catches. Mitigations:
+   - **The Phase 2 extension verifies each load:** hash the served wallet bundle, compare against the registry CID, badge ✅/❌ in the popup. A targeted swap becomes detectable by any extension user, which deters it against all users. This is the extension's *primary* job (M6), ahead of AI explanations.
+   - **Service-worker pinning helps incidentally:** returning users run cached code, so a swap doesn't reach them until refresh — widening the detection window.
+   - **Standards track:** adopt browser-native web app integrity/transparency (manifest-pinned, publicly logged bundles) when it ships; the extension is the practical substitute until then.
+
+Residual gap, stated honestly in SECURITY.md: a first-time user with no tools trusts DNS + TLS + the deploy pipeline for that first load — like every web wallet; unlike most, we say so.
+
+---
+
+# Phase 2 — AI Inspection Extension
+
+**Goal:** A standalone browser extension with three jobs, in priority order: (a) verify that the wallet origin serves the registry-listed build (served-bytes integrity, see M5 Verifiability), (b) analyze the dapp a user is visiting (the AI inspection feature moved out of the SDK), and (c) explain grants in plain language during STANDARD-mode approval.
+
+**Why move it out of the SDK:**
+- Inside the SDK it runs in the host realm — a malicious host can suppress or falsify its own inspection. An extension is an independent trust surface the host cannot touch.
+- It removes the Rukh/AI dependency (and its bundle weight and sponsored-API coupling) from the core signing path, keeping the wallet origin minimal and auditable.
+
+**Role boundary (invariant):** the extension is a **comprehension layer, never a security dependency**. The popup's own decoding + simulation must remain sufficient for a safe decision — most users won't have the extension, and non-Chromium browsers exist.
+
+## Milestones
+
+### M6 — Extension MVP: bundle verification + standalone dapp inspection
+
+- **Wallet-bundle integrity check (primary):** on each wallet-origin load, hash the served bundle, compare against the onchain registry CID, badge ✅/❌ in the popup and extension icon. Requires M5's reproducible-build + registry pipeline to exist first.
+- Port `inspect`/`gatherCode` browser logic to an MV3 extension: user visits a dapp, clicks the extension, gets the Rukh-generated security report (transaction methods, signing patterns, red flags) in the extension UI.
+- Deprecate `inspect`/`inspectNow` in the SDK (keep the Node.js variant for CI/dev workflows).
+- Privacy: page content is sent to the Rukh API — explicit consent on first use, per-site opt-in, document what is transmitted. (The integrity check is fully local — hashing only, nothing transmitted.)
+
+### M7 — Grant explanation in the approval flow
+
+- When the wallet popup opens for grant approval, it signals the extension (wallet-origin ↔ extension messaging via `externally_connectable`, pinned to the extension ID; never through the host page).
+- The extension fetches/produces a plain-language explanation: *"This game is asking to spend up to 0.1 ETH from your GAMING budget on two contracts (its game contract and USDC) until Friday, without asking each time. It also wants silent message signing — typical for game session logins."*
+- Rendered in the popup as an annotation clearly attributed to the extension, alongside — never replacing — the popup's native decoded view. Absence of the extension degrades gracefully to the native view.
+- Flag mismatches: grant requests exceeding what the inspected dapp code appears to need (e.g. asks for token-approval rights but its code never calls approve).
+
+### M8 — Trust & distribution
+
+- The extension is now itself a trust surface: pin its ID in the wallet origin's allowlist, sign releases, extend IPFS build-verification to extension builds, publish to Chrome Web Store (Firefox port later).
+- Fallback path: the popup can offer the same Rukh-generated explanation via a direct wallet-origin → Rukh call for users without the extension (marked as such), keeping the extension optional rather than privileged.
+
+---
+
+# Security invariants (both phases)
+
+1. No private key or mnemonic ever crosses the postMessage boundary, in any mode — including YOLO.
+2. Raw-hash signing is never silent.
+3. App identity comes from transport-level `event.origin`, never from the payload.
+4. `approve`/`permit`-class signatures always escalate to trusted UI.
+5. The wallet-origin bundle (and later the extension) is registry-verified (IPFS CID) like the SDK itself; builds are reproducible.
+6. The extension informs and verifies; it never authorizes. The popup + biometric remain the only consent path.
+7. Trust is consolidated, not eliminated: the wallet origin is the trusted computing base, and the docs say so.
+
+# Sequencing
+
+Phase 1: M1–M2 first — the custody boundary is the entire point. M3–M4 in parallel once transport is stable. M5 gates GA. Phase 2 starts after M4 exists (the popup is the extension's integration point); the dapp-inspection half of M6 can begin earlier as a standalone port, but its integrity-check half depends on M5's reproducible-build pipeline.
+
+# Future path (out of scope)
+
+The grant JSON is deliberately enforcement-agnostic. If onchain enforcement (EIP-7702 session keys, gas sponsorship via 4337) becomes worth it, the same grants compile to an audited delegate's permission module — an upgrade per grant, not a redesign.

package/docs/notes/JULY_13_ROADMAP.md

@@ -0,0 +1,29 @@
+# July 13 Roadmap
+
+Issue/PR titles for w3pk, derived from [SYNCING_ACROSS_DEVICES.md](SYNCING_ACROSS_DEVICES.md) and [IFRAME_IMPLEMENTATION_PLAN.md](IFRAME_IMPLEMENTATION_PLAN.md), following the project's PR naming convention (imperative, sentence case, backticks for code identifiers).
+
+---
+
+## 1. Remove AI inspection
+
+1. Remove AI inspection from the SDK
+
+## 2. Syncing across devices
+
+2. Add PRF-based passwordless device sync
+   - PRF key derivation in `crypto.ts`, `prf` encryption method for backup files, PRF payloads in `exportForSync()` and `syncWalletWithPasskey`
+3. Fix fresh-device sync flow
+   - Wallet persistence when no local credential exists, remove login requirement from `importFromSync`, replace the dead-end login error with a typed `SyncRequiredError`
+
+## 3. Cross-origin iframe wallet
+
+4. Add wallet origin with postMessage RPC transport
+   - Static bundle at `wallet.w3pk.w3hc.org`, handshake + origin checks + nonces, SDK becomes a thin RPC client
+5. Move key custody into the wallet origin
+   - WebAuthn under the wallet RP ID, HD derivation and EIP-7951 signing in-origin, remove key export from the cross-origin API, one-time credential re-registration flow
+6. Add policy engine and grant approval flow
+   - Grant schema and per-origin storage, enforcement pipeline, hard rules for `approve`/`permit` and raw-hash signing, mode presets as grant templates, grant management screen
+7. Add confirmation popup
+   - Calldata decoding and simulation, fresh WebAuthn assertion for approvals, popup-blocked redirect fallback
+8. Harden and release the wallet origin
+   - CSP/COOP/frame-ancestors, onchain build verification of the wallet bundle, hostile-host test suite, service worker for availability, break-glass recovery mirror, SECURITY.md update

package/docs/notes/NOTES.md

@@ -0,0 +1,333 @@
+# w3pk Security Audit Findings
+
+**Target:** [w3hc/w3pk](https://github.com/w3hc/w3pk) — `114-audit` branch
+**Commit:** `c82a69affb472598babd7570c3e57613a84e7162`
+**Scope:** `src/` per README, excluding `src/inspect`, `src/zk`, `src/education`, plus the
+`docs`, `examples`, `scripts`, `standalone`, and `test` folders. Solidity contract excluded.
+**Codebase size:** ~11,904 lines of TS/JS in scope.
+
+> This document is an independent code review, **not** a substitute for a full professional
+> audit. It reflects manual reading of the security-critical modules (wallet/key derivation,
+> backup encryption, Shamir recovery, social recovery, stealth addresses, origin derivation,
+> SIWE, sync, persistent sessions). It has not been fuzzed, formally verified, or run against
+> a test suite. Absence of a finding in a module is not proof that module is safe.
+
+---
+
+## Severity summary
+
+| # | Severity | Finding | Location | Status |
+|---|----------|---------|----------|--------|
+| 1 | Critical | Wallet encryption key derived entirely from public WebAuthn data | `src/wallet/crypto.ts` | ✅ FIXED |
+| 2 | Critical | Broken `recoverFromShares` threshold logic in backup-based recovery | `src/recovery/backup-based-recovery.ts` | ✅ FIXED |
+| 3 | High | Hardcoded constant salt in WebAuthn KDF | `src/wallet/crypto.ts` | ✅ FIXED |
+| 4 | High | Stealth scalars not reduced mod curve order (ERC-5564) | `src/stealth/crypto.ts` | ✅ FIXED |
+| 5 | Medium | GF(256) table construction in Shamir needs verification | `src/recovery/shamir.ts` | |
+| 6 | Medium | Shamir share combination has no integrity/authenticity check | `src/recovery/shamir.ts`, recovery managers | |
+| 7 | Medium | P-256 → Ethereum address derivation skips EIP-55 checksum | `src/wallet/origin-derivation.ts` | |
+| 8 | Medium | Origin-derived index uses only 32 bits of SHA-256 with modulo bias | `src/wallet/origin-derivation.ts` | |
+| 9 | Medium | Persistent sessions: at-rest mnemonic protection inherits findings #1/#3 | `src/core/persistent-session.ts` | |
+| 10 | Low | Weak password-strength acceptance threshold | `src/backup/encryption.ts` | |
+| 11 | Low | Guardian shares transported/stored with weak handling guidance | `src/recovery/social.ts` | |
+| 12 | Low | SIWE parser is hand-rolled and diverges from EIP-4361 ABNF | `src/siwe/index.ts` | |
+| 13 | Low | Device fingerprint and sync-method detection are spoofable | `src/backup/encryption.ts`, `src/sync/*` | |
+| 14 | Info | Deprecated `deriveEncryptionKey` (v2) still present | `src/wallet/crypto.ts` | |
+| 15 | Info | `console.error`/`console.warn` may leak diagnostic detail | multiple | |
+
+---
+
+## 1. Critical — Wallet encryption key derived entirely from public WebAuthn data
+
+**File:** `src/wallet/crypto.ts` — `deriveEncryptionKeyFromWebAuthn`
+
+The AES-GCM key protecting the BIP39 mnemonic is derived solely from `credentialId` and,
+optionally, the WebAuthn `publicKey`:
+
+```
+keyMaterial = `w3pk-v4:${credentialId}:${publicKey}`
+```
+
+Both inputs are **public**. The WebAuthn `credential.id` is transmitted in the clear and stored
+next to the ciphertext (`src/auth/authenticate.ts` persists `credentialId: credential.id`); the
+public key is public by definition. The biometric/PIN prompt gates only the *ceremony*, not the
+key material — no authenticator secret (PRF / `hmac-secret` output, signature, UV-derived value)
+enters the KDF.
+
+**Impact:** Anyone holding the ciphertext plus the credential ID (which travels with it) can
+recompute the key offline and decrypt the mnemonic. The 210,000 PBKDF2 iterations add nothing
+because the "password" is a known constant. This is a full break of the WebAuthn-protected
+encryption.
+
+**Propagation:** the same primitive is reused in `src/sync/vault.ts` (`createSyncPackage` /
+`restoreFromSync`), `src/sync/backup-sync.ts` (passkey export/import), and
+`src/core/persistent-session.ts`. All inherit the weakness.
+
+**Recommendation:** Use the WebAuthn **PRF extension** (or `hmac-secret`) to obtain a
+per-credential secret that never leaves the authenticator and feed that into the KDF. The
+encryption key must depend on a value an attacker holding the ciphertext cannot reconstruct.
+
+---
+
+## 2. Critical — Broken `recoverFromShares` threshold logic
+
+**File:** `src/recovery/backup-based-recovery.ts` — `SocialRecovery.recoverFromShares`
+
+This method calls `combineShares(shareBytes, shares.length)` — it passes the **number of shares
+provided** as the threshold, rather than the **threshold the secret was actually split with**.
+
+```
+const recoveredBytes = combineShares(shareBytes, shares.length);
+```
+
+In `shamir.ts`, `combineShares(shares, threshold)` uses `shares.slice(0, threshold)` and
+Lagrange-interpolates assuming the polynomial degree is `threshold - 1`. If the caller supplies
+a number of shares different from the original split threshold, interpolation reconstructs the
+**wrong** secret (silently, since GF(256) interpolation always returns *a* value). The only thing
+catching it afterward is a JSON-parse + address-match check, which will usually throw "invalid
+shares" — but can in principle yield a corrupted-but-parseable result.
+
+The companion implementation in `src/recovery/social.ts` (`recoverFromGuardians`) does this
+**correctly**, reading `threshold` from the embedded share metadata. The two recovery managers
+are inconsistent, and the `backup-based-recovery.ts` one is wrong.
+
+**Impact:** Recovery via this code path fails (or, worst case, mis-reconstructs) whenever the
+number of presented shares ≠ the original threshold — which is the normal case when more than the
+minimum number of guardians respond. Loss-of-access risk for funds protected by social recovery.
+
+**Recommendation:** Embed the original `threshold` in each share's metadata and always pass that
+value to `combineShares`. Add round-trip tests for `M < provided ≤ N`.
+
+---
+
+## 3. High — Hardcoded constant salt in WebAuthn KDF
+
+**File:** `src/wallet/crypto.ts` — `deriveEncryptionKeyFromWebAuthn` (and deprecated
+`deriveEncryptionKey`)
+
+The PBKDF2 salt is a fixed value derived from the literal string `"w3pk-salt-v4"` (and
+`"w3pk-salt-v2"`). A constant, globally known salt gives no per-user separation and permits
+precomputation across all users.
+
+**Note:** the password-based backup path in `src/backup/encryption.ts` does this correctly
+(random per-encryption salt). The WebAuthn path should follow that pattern.
+
+**Recommendation:** Generate a random unique salt per encryption and store it with the ciphertext.
+
+---
+
+## 4. High — Stealth scalars not reduced modulo the curve order
+
+**File:** `src/stealth/crypto.ts` — `multiplyGeneratorByScalar`, `addPrivateKeys`
+
+The ERC-5564 routines hash the ECDH shared secret with `keccak256` and use the raw 32-byte result
+directly as a secp256k1 scalar:
+
+- `multiplyGeneratorByScalar(hashedSharedSecret)` calls `new ethers.Wallet(scalar)` on the raw
+  hash. If the hash is `0` or `≥ n` (curve order), ethers throws — a small but nonzero failure
+  probability per announcement, producing intermittent, hard-to-reproduce errors.
+- `addPrivateKeys` reduces `(k1 + k2) mod n` correctly, but the `s_h` term entering it is the
+  unreduced hash; the spec computes `s_h` as a scalar and consistency between the public-key side
+  (`s_h × G`) and the private-key side (`spending_privkey + s_h`) requires the **same reduced
+  scalar** be used on both sides.
+
+Because the public-key path (`multiplyGeneratorByScalar`) and the private-key path
+(`addPrivateKeys`) treat `s_h` inconsistently with respect to reduction, there is risk that a
+derived stealth address cannot be spent by the derived private key in edge cases.
+
+**Additional concern:** `addPublicKeys` implements raw secp256k1 point addition in `BigInt` with
+no handling for the point-at-infinity case (`x1 === x2 && y1 !== y2`), and uses `computeSharedSecret`
+returning a value treated as the ECDH x-coordinate hashed directly — verify it matches the ERC-5564
+shared-secret definition (the standard hashes the compressed shared point, conventions vary).
+
+**Impact:** Potentially unspendable stealth funds in edge cases; intermittent failures.
+
+**Recommendation:** Reduce `s_h` mod `n` once, reject `0`, and use that single reduced scalar on
+both the public-key and private-key sides. Use a vetted secp256k1 library (e.g. `@noble/secp256k1`)
+for point/scalar arithmetic rather than hand-rolled BigInt math, and add cross-check tests asserting
+`address(stealthPrivKey) === stealthAddress` over many randomized runs.
+
+**Fix:** Implemented `reduceScalarModN()` function that:
+- Reduces any scalar modulo the secp256k1 curve order `n`
+- Validates the scalar is in the range `[1, n-1]`
+- Rejects zero scalars with proper error handling
+
+Updated all three stealth address functions (`generateStealthAddress`, `checkStealthAddress`,
+`computeStealthPrivateKey`) to reduce `hashedSharedSecret` using `reduceScalarModN()` before
+using it in either public-key or private-key operations. This ensures the same properly-reduced
+scalar `s_h` is used consistently on both code paths, eliminating the risk of unspendable funds
+and intermittent failures.
+
+---
+
+## 5. Medium — GF(256) table construction in Shamir needs verification
+
+**File:** `src/recovery/shamir.ts` — `GF256`
+
+Log/exp tables are built for indices 0–254 followed by `EXP_TABLE[255] = EXP_TABLE[0]`. `divide`
+computes `(LOG[a] - LOG[b] + 255) % 255` (range 0–254) and `multiply` reduces by `% 255`, so the
+`EXP_TABLE[255]` entry is dead but harmless. The real risk is that a subtle off-by-one in field
+construction silently corrupts recovered secrets without throwing.
+
+**Recommendation:** Add an exhaustive round-trip test
+(`combineShares(splitSecret(x, t, n), t) === x`) over all 256 byte values and representative
+`(t, n)` pairs, plus known-answer vectors against a reference implementation. Gate the recovery
+feature on this.
+
+---
+
+## 6. Medium — Shamir share combination has no integrity/authenticity check
+
+**Files:** `src/recovery/shamir.ts` (`combineShares`); `src/recovery/social.ts`,
+`src/recovery/backup-based-recovery.ts`
+
+`combineShares` blindly takes the first `threshold` shares and interpolates. A single corrupted or
+maliciously crafted share silently yields a wrong secret. Downstream JSON-parse + address-match
+checks catch *most* corruption but are not cryptographic integrity guarantees, and a malicious
+guardian can grief recovery by submitting a bad share that's indistinguishable until reconstruction
+fails.
+
+**Recommendation:** Use an authenticated share format — e.g. include a hash commitment to the
+secret and/or a per-share MAC so individual shares can be validated before combination, and so a
+bad share can be attributed.
+
+---
+
+## 7. Medium — P-256 → Ethereum address derivation skips EIP-55 checksum
+
+**File:** `src/wallet/origin-derivation.ts` — `deriveAddressFromP256PublicKey`
+
+The function returns `'0x' + hash.slice(-40)` directly (lower-case, unchecksummed), unlike the rest
+of the codebase which uses `ethers.getAddress(...)`. Downstream comparisons that assume EIP-55
+checksumming (e.g. strict equality against a checksummed address) can produce false mismatches, and
+unchecksummed addresses surfaced to users reduce typo protection.
+
+**Recommendation:** Wrap the result in `ethers.getAddress(...)`.
+
+---
+
+## 8. Medium — Origin-derived index uses 32 bits of SHA-256 with modulo bias
+
+**File:** `src/wallet/origin-derivation.ts` — `deriveIndexFromOriginModeAndTag`
+
+The derivation reads only the first 4 bytes of the SHA-256 digest (`getUint32(0)`) and computes
+`uint32 % MAX_INDEX` where `MAX_INDEX = 0x7fffffff`. Two issues: (a) only 32 bits of entropy feed
+the index, and (b) `2^32 % (2^31 - 1)` introduces a small modulo bias toward low indices. While
+BIP32 non-hardened indices are inherently public and this is not a secret, collisions between
+distinct (origin, mode, tag) tuples would map two different sites to the **same** derived wallet,
+which is a correctness/privacy concern.
+
+**Recommendation:** Document the collision model explicitly, or widen the index space and use
+rejection sampling instead of modulo to remove bias.
+
+---
+
+## 9. Medium — Persistent sessions inherit the WebAuthn at-rest weakness
+
+**File:** `src/core/persistent-session.ts`
+
+Persistent sessions store an `encryptedMnemonic` in IndexedDB, encrypted via
+`deriveEncryptionKeyFromWebAuthn` (findings #1/#3). The module correctly refuses to persist
+`STRICT` mode and enforces expiry, but "remember me" here means a mnemonic encrypted with public
+inputs sits at rest in the browser. The `credentialId` is also stored in the same record, i.e. the
+ciphertext and the (public) key-derivation input live together.
+
+**Recommendation:** Fix #1/#3 first; persistent sessions are only as strong as the underlying KDF.
+Consider also requiring a fresh WebAuthn assertion (UV) to unwrap the session even when "remember
+me" is on.
+
+---
+
+## 10. Low — Weak password-strength acceptance threshold
+
+**File:** `src/backup/encryption.ts` — `validatePasswordStrength`
+
+Accepts `valid: true` at `score >= 50` with no remaining feedback — satisfiable with length plus
+two character classes, weak for a wallet backup password.
+
+**Recommendation:** Raise the bar and/or adopt an entropy estimator (e.g. zxcvbn) instead of a
+heuristic score.
+
+---
+
+## 11. Low — Guardian-share handling guidance encourages risky storage
+
+**File:** `src/recovery/social.ts` (and `backup-based-recovery.ts`)
+
+The generated guardian explainer text states shares are "Safe to store digitally" and suggests
+screenshots. While a single share below threshold is individually useless, the human-facing copy
+underplays that an attacker collecting `threshold` shares (e.g. via compromised cloud backups of
+several guardians) fully reconstructs the **password-encrypted** backup — whose password may itself
+be weak (finding #10). Guidance should emphasize that shares are sensitive and that the backup
+password is the last line of defense.
+
+**Recommendation:** Tighten the guardian instructions; recommend offline/encrypted storage and warn
+against screenshots/unencrypted cloud.
+
+---
+
+## 12. Low — Hand-rolled SIWE parser diverges from EIP-4361 ABNF
+
+**File:** `src/siwe/index.ts` — `parseSiweMessage` / `validateSiweMessage`
+
+The parser splits on lines and pattern-matches prefixes rather than following the EIP-4361 ABNF.
+Edge cases (statements containing lines that begin with field prefixes, missing/optional-field
+ordering, CRLF vs LF, resources block termination) can be mis-parsed. SIWE messages are a security
+boundary for authentication; parser ambiguity can enable confusion between what a user signed and
+what a server validates. `validateSiweMessage` also does not verify the signer address against the
+recovered signature (out of this function's scope, but worth confirming the caller does).
+
+**Recommendation:** Use a maintained SIWE library (e.g. the `siwe` package or viem's helpers), or
+add a conformance test corpus. Ensure callers always verify the signature recovers to `address`.
+
+---
+
+## 13. Low — Device fingerprint and platform detection are spoofable
+
+**Files:** `src/backup/encryption.ts` (`getDeviceFingerprint`), `src/sync/*` (UA sniffing)
+
+`getDeviceFingerprint` is already documented as non-cryptographic; confirmed it must never enter key
+material (it currently does not). Sync-method/platform detection relies on `navigator.userAgent`
+substring checks, which are trivially spoofable and brittle. These are used only for UX routing, so
+impact is low, but they should not gate any security decision.
+
+**Recommendation:** Keep fingerprint strictly out of key derivation; treat platform detection as a
+non-authoritative hint.
+
+---
+
+## 14. Info — Deprecated v2 KDF still present
+
+**File:** `src/wallet/crypto.ts` — `deriveEncryptionKey`
+
+The `@deprecated` v2 derivation remains exported and shares the same structural flaws as #1/#3
+(public inputs + constant salt). Dead crypto paths are a foot-gun.
+
+**Recommendation:** Remove once migration is complete, or clearly fence it behind a one-way
+migration routine.
+
+---
+
+## 15. Info — Diagnostic logging
+
+Several modules use `console.error` / `console.warn` (e.g. `device-manager.ts`, `social.ts`,
+sync paths). Confirm no secret material (mnemonic, private key, share data, credential secrets) is
+ever logged, including in error objects passed to the custom `*Error` wrappers.
+
+---
+
+## Overall assessment
+
+The architecture (WebAuthn-gated wallet, password-encrypted backup files, Shamir social recovery,
+ERC-5564 stealth, origin-scoped derivation) is reasonable, and the **password-based** backup
+encryption is implemented to a good standard (random salt, AES-256-GCM, 310k PBKDF2 iterations).
+
+However, the **WebAuthn-protected** confidentiality story is fundamentally broken (#1, #3, #9): the
+key is derived from public values, so any party holding the stored ciphertext can decrypt it. There
+is also at least one **correctness bug in social recovery** (#2) that can prevent legitimate
+recovery, and the **hand-rolled cryptography** in stealth addresses (#4) and Shamir (#5/#6) needs
+either replacement with vetted libraries or exhaustive test coverage before it can be trusted with
+funds.
+
+**Recommendation:** Treat findings #1, #2, #3, and #4 as release blockers. After remediation, this
+code should still undergo a full third-party audit (with fuzzing and known-answer vectors for all
+crypto primitives) before being used to store meaningful value.