Audit du dépôt sp-wallet avant le développement natif (2026-11-18)
Dépôt audité : ~/Desktop/Cluster/projets/sp-wallet, branche v11 = production 52e513b (API + web sur M2M32c:8650, signataire isolé
seul sur m6ma:8651). Lu en entier pour le chemin de sécurité ; chaque domaine a ensuite été relu route par route pour son portage dans
../SPWalletCore. Aucune modification du backend n'a été faite par ce projet (les ajouts additifs pour clients natifs sont faits par
la session macOS, branche native-clients).
1. Modèle de garde (docs/adr/0001-custody.md, services/isolated-signer)
- Les clés existent uniquement dans le signataire : un processus seul sur une machine dédiée, clé logicielle chiffrée, joignable par l'API seule (HMAC + liste d'adresses source). Ni l'API, ni le site, ni une app ne peuvent les lire.
- Le signataire épingle lui-même les clés publiques des passkeys et vérifie chaque assertion indépendamment de l'API : origine et rpId de sa propre configuration, vérification de l'utilisateur exigée.
- La clé du portefeuille (compte HD 0) ne signe jamais sans une assertion fraîche dont le défi est le SHA-256 de l'objet canonique
approuvé — à une exception bornée (premier
mintd'un pont déjà approuvé). - Sept chemins signent sans passkey par opération ; chacun repose sur une autorité permanente approuvée par passkey (mandat d'agent, autorisation de plateforme, mandat dérivé, mandat de cotation…) et est borné par le signataire seul (ADR, tableau des sept lignes).
- Limites dans
policy.jsonsur la machine du signataire : par transfert, par jour UTC et par actif, plafond de frais par réseau, fenêtre d'approbation maximale, liste blanche facultative, section NFT. Arrêt d'urgence : l'API peut l'activer, seul l'opérateur sur la machine du signataire peut le lever. - Rien de ce que le signataire signe n'est un octet opaque venu de l'API : la transaction est reconstruite depuis les champs approuvés ou décodée et vérifiée champ par champ.
2. Authentification et session (services/api/src/auth.ts, server.ts)
- WebAuthn (SimpleWebAuthn), rpId
wallet.spboucher.ai, origine attenduehttps://wallet.spboucher.ai, UV exigée, clé résidente. Une passkey native Apple produit cette même origine dansclientDataJSON: aucun changement du signataire ni de l'API n'est nécessaire pour un client natif, hormis le fichier d'association de domaine (AASA) listant l'app. - Session : cookie HttpOnly
__Host-spw, SameSite=Strict, 30 minutes d'inactivité, 12 heures au plus, révocable. Pas de jeton porteur. - Toute requête non-GET exige
Origin= l'origine du portefeuille etX-SPW-CSRF: 1. Vérifié contre la pile jetable : une écriture sans ces en-têtes est refusée (403) même avec un cookie valide. - Ajout d'une passkey : la nouvelle clé n'est épinglée par le signataire qu'avec une assertion d'une clé déjà enrôlée sur
SHA-256("SPW-ENROLL-v1\n" + id + "\n" + cléPublique).
3. Approbation liée à l'intention (packages/core/src/intent.ts)
- Objet
Intent(schéma strict) : identité de la proposition, clé, réseau etchainRef, actif, montant, source, destination, plafond de frais, création, expiration, version de politique, section de chaîne (evm / btc / sol / x), et au plus une section d'opération (swap, bridge, xswap, venueDeposit, gmx). - Octets canoniques :
"SPW-INTENT-v1" || 0x00, puis pour chaque champ dans l'ordre fixé par le code : u16 BE (longueur de la clé), u32 BE (longueur de la valeur), clé, valeur. Défi = SHA-256 de ces octets. 28 domaines canoniques existent au total (trois sérialisations) ; tous sont portés dans le Core et vérifiés contre 100+ vecteurs générés par le code TypeScript du backend. - Constat : pour un transfert,
request-approvalrenvoieintent+options, donc un client peut recalculer le défi. Pour swap / bridge / xswap / plans et trois suites de pont, la production ne renvoie PAS l'objet haché : le client web signe ce défi à l'aveugle (le signataire, lui, vérifie tout). Les clients natifs refusent cette approbation aveugle (ApprovalError.unsupported) jusqu'au déploiement de la branchenative-clientsqui ajoute ces champs.
4. Machine à états et diffusion (packages/core/src/state.ts, transfers.ts)
draft → pending_approval → approved → signed → broadcast → confirming → finalized, avec rejected, expired, failed, replaced,
reorged, not_broadcast. Une transaction diffusée n'est pas confirmée ; seule finalized est un succès. Idempotence par
Idempotency-Key + empreinte de la requête ; une proposition par réseau en vol ; proposition à usage unique.
5. Maturité réelle par domaine (lue dans le code ; « jamais exécuté » = d'après les documents du backend)
| Domaine | État réel sur le serveur |
|---|---|
| Réseaux | 23 réseaux (8 EVM, Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, Solana, TRON, XRPL, Stellar, Aptos, Cosmos, Sui, NEAR, TON, Cardano, Polkadot Asset Hub) : soldes, envoi, réception. Envois réels effectués par le propriétaire sur Ethereum seulement ; les autres chemins de diffusion n'ont jamais servi en réel |
| Jetons | registre généré et vérifié (84 symboles) ; pas de jeton personnalisé libre (seul le registre est accepté) |
| Swaps | cotations : tous les fournisseurs activés ; exécution : KyberSwap sur 8 réseaux EVM, Jupiter sur Solana ; un seul swap réel (Ethereum) |
| Ponts | CCTP USDC sur 7 réseaux EVM + Solana ; THORChain natif (BTC, LTC, ETH et jetons épinglés) ; plans à 3 étapes au plus ; prouvés sur forks / simulation, un pont réel vers Arbitrum corrigé le 2026-11-17 |
| NFT | lecture : Solana (4 standards), EVM (ERC-721/1155, découverte selon configuration) ; transferts par passkey ; marché en lecture seule ; écritures de marché non construites ; inscriptions Bitcoin non gérées |
| Dérivés | Hyperliquid : données, papier, réel manuel (passkey par ordre), collatéral ; GMX : construit, verrou fermé ; dYdX et edgeX : données seulement (conditions excluant le Canada) |
| Ordres / risque | table d'ordres unifiée, moteur de risque, interrupteur général (levée par passkey), mandats de trading |
| Agents | simulation (labo), papier, réel au comptant sous mandat, perpétuels réels sous mandat dérivé, market making (preuves négatives) |
| Alertes | 66 types, Web Push seulement (aucune voie APNs), webhook |
| Recherche | travaux par un exécuteur distant ; résultats distingués par auteur (agent / serveur) |
Verrous d'environnement lus : SPW_BROADCAST, SPW_DERIV_LIVE_MAINNET, SPW_DERIV_MANDATE_MAINNET, SPW_DERIV_GMX_LIVE,
SPW_DERIV_MM_MAINNET, SPW_DERIV_MM_TESTNET, SPW_TRADING_API_EXECUTION, NFT_ENABLED. Leur état en production appartient au
propriétaire ; l'app affiche ce que le serveur déclare, sans le supposer.
6. Conséquences pour l'app native
- Aucune clé, aucune phrase de récupération, aucune signature de transaction dans l'app : elle consulte, prépare et autorise.
- Toute approbation passe par
ApprovalBinding.verify: défi recalculé depuis l'objet affiché, rpId vérifié, UV exigée, objet comparé à la demande. Un champ inconnu dans un objet canonique est un refus, pas une omission. - Le verrou Face ID / Touch ID de l'app ne remplace jamais l'assertion WebAuthn.
- Le serveur n'offre pas d'APNs : notifications locales à partir des alertes confirmées par le serveur seulement.
- Tests financiers uniquement sur une pile jetable (clés aléatoires, fork local, diffusion hors réseau réel).