Repository Public
1# SP Wallet macOS — security review of the client23Scope: the native macOS client. The custody model, the signer and the API are those of the backend4(`sp-wallet/docs/adr/0001-custody.md`, `docs/threat-model/threat-model.md`); nothing in them was changed for this app except two5additive, reviewed items listed in §6. No independent audit or penetration test has been performed on this client.67## 1. What the client holds89| Item | Where | Protection |10|---|---|---|11| Private keys, seed, recovery phrase | **nowhere** — the app has no code path to them; the API exposes no route | — |12| Session token (the `__Host-spw` cookie value) | Keychain (data-protection keychain, `WhenUnlockedThisDeviceOnly`, not synchronized) | erased at sign-out and when the server refuses it |13| Read-only snapshots (balances, public addresses, history, NFT lists), value history | sandbox container, `completeFileProtection`, excluded from backups | erased by "Se déconnecter et effacer" |14| Passkey | the system (iCloud Keychain / Secure Enclave) — never visible to the app | system |15| Trading-API secrets shown once | memory only, for the lifetime of the sheet | never written |1617## 2. Authorization path (the part that must not fail)18191. The app asks the server to prepare an operation. The server answers with a canonical object and WebAuthn options.202. **The app recomputes SHA-256 of the canonical serialization itself** (`SPWalletCore`, byte-for-byte ports verified against 10021 vectors generated by the backend's own TypeScript for 28 domains) and refuses to continue unless the challenge equals that hash,22 the relying party is `wallet.spboucher.ai` and user verification is required (`ApprovalBinding.verify`).233. It also checks that the object is the operation that was asked (network, asset, amount, destination, memo, expiry).244. The review sheet renders the fields **of that verified object** — never the server's summary — with full addresses, exact25 base-unit amounts, fee ceiling, contracts called and spend approvals (`Components/TransactionReview.swift`).265. Only then the system passkey sheet is shown. The assertion goes to the API, which forwards it to the isolated signer; the signer27 verifies the assertion against the passkeys it pinned itself, rebuilds the transaction from the same fields and applies its limits.2829Consequences: a compromised API or network path cannot make this app ask the passkey to sign something other than what is on30screen; a compromised *app binary* still can (as any client can) — the signer's limits and the passkey's per-operation scope bound31that case, exactly as for the web client. The local app lock (Touch ID) authorizes nothing.3233An object the app cannot recompute is never approved (`ApprovalError.unsupported` → the UI states it, with no bypass).3435## 3. Tests of the path (development variant against a throwaway stack: real API, real signer process, random test keys)3637Run with `Scripts/run-dev.sh --selftest` (see `docs/TEST_REPORT.md` for the last result):38tampered intent refused by the binding · cancelled passkey signs nothing (proposal stays pending) · replay of an approval refused ·39malformed address / own address / excess decimals refused before any preparation · unfunded transfer refused by the server ·40emergency halt blocks transfers (`--halt`) · sign-out closes the session server-side and removes the token · success only at41`finalized`.4243## 4. Platform hardening4445App Sandbox (outgoing network + user-selected files only), Hardened Runtime, no JIT / unsigned-memory / library-validation46exception, no web engine linked (checked by `Scripts/verify-release.sh`), ATS without exception in Release, redirects not followed by47the API client, CSRF header + exact `Origin` on every state-changing call, associated domain limited to48`webcredentials:wallet.spboucher.ai`, explorer links restricted to `https`, CSV export neutralizes formula injection, logs carry no49token, address or amount at public privacy level.5051## 5. Development variant5253`SP Wallet Dev` (bundle `ai.spboucher.spwallet.dev`) is a different app: own container and keychain item, local stack only54(`http://localhost`), software passkey, scripted self-test. All of it is inside `#if SPW_DEV`; `verify-release.sh` fails the55release if any of its strings is found in the Release binary.5657## 6. Backend changes made for native clients (deployed 2026-11-18, commit `8dc85bd`, with the owner's approval)5859- `GET /.well-known/apple-app-site-association` — `webcredentials` for the two app identifiers; grants no session and no route.60- Preparation routes of swaps, bridges, cross-chain swaps, mint retry, reclaim and Solana token-account now also return the61 canonical object their challenge is the hash of (additive fields). Without them a native client could not verify those approvals.62 The signer is unchanged.6364## 7. Known limits6566- The passkey sheet of macOS shows the domain, not the transaction: the binding is verified by the app, not displayed by the system.67- A swapped app binary defeats client-side verification; distribution is Developer ID signed and notarized, and the signer's limits68 remain the last line.69- Observations of the backend's address validation reported during the Swift port (not changed): U+212A accepted by case folding on70 upper-case BCH/Cardano addresses (normalized output correct); zero/burn addresses accepted on XRPL, Stellar, Bitcoin-family,71 Cosmos and Solana; `bridgeView` falls back to stage `done` for an unknown phase. The native validator is at parity with the backend (differential test over 9,774 cases): it refuses a zero address where the72 backend does (EVM, Sui, Aptos…) and, like the backend, not on those five families. Changing that is a backend decision.73