Intégration wallet

Intégrez le SDK client Unlukey dans un wallet pour avertir les utilisateurs lorsque leur phrase de récupération a été générée par une vulnérabilité connue de génération de seed faible.

Le SDK est publié dans le dépôt coinspect/unlukey.

Comment fonctionne la vérification

  1. Le wallet dérive l’entropie BIP-39 à partir de la phrase de récupération.
  2. Le SDK client hache l’entropie avec SHA-256 et prend un court préfixe du hash obtenu.
  3. Il récupère uniquement le bucket du dataset correspondant à ce préfixe depuis un hébergement statique.
  4. Il compare localement les octets restants du hash aux entrées de ce bucket.

Le préfixe regroupe de nombreuses clés possibles dans le même bucket (k-anonymat). L’hébergeur statique ne voit que le bucket demandé, jamais la clé complète vérifiée ni si elle correspond.

Les datasets sont séparés par longueur d’entropie : un dataset pour l’entropie 128 bits (12 mots) et un pour 256 bits (24 mots). Le client sélectionne automatiquement le bon.

Installation

npm install @unlukey/client

(Tant que le paquet n’est pas publié, installez-le directement depuis le dépôt : npm install github:coinspect/unlukey#path:client.)

Utilisation de base

import { check } from '@unlukey/client'
import { mnemonicToEntropy } from '@scure/bip39'
import { wordlist } from '@scure/bip39/wordlists/english'

const entropy = mnemonicToEntropy(secretRecoveryPhrase, wordlist)

const { vulnerable } = await check(entropy)

if (vulnerable) {
  // Avertissez l'utilisateur : cette phrase de récupération correspond à
  // une seed faible connue et les fonds doivent être déplacés vers un
  // nouveau wallet.
}

La logique de recherche s’exécute côté client. La phrase de récupération et l’entropie ne quittent jamais l’appareil ; seul un préfixe du hash de l’entropie est envoyé à l’hébergeur du dataset. entropy est un Uint8Array et doit contenir :

  • 16 octets, pour les mnémoniques de 12 mots, ou
  • 32 octets, pour les mnémoniques de 24 mots.

Interpréter le résultat

check() renvoie { vulnerable, key, prefix, bucketPath, reason? } :

  • vulnerable: true — l’entropie correspond à une seed faible connue. Invitez l’utilisateur à déplacer ses fonds vers un nouveau wallet généré avec une source d’aléa sécurisée.

  • vulnerable: false — aucune correspondance trouvée. Cela ne prouve pas que la phrase de récupération est sûre ; cela signifie seulement qu’elle ne correspond à aucun candidat dans les datasets actuels d’Unlukey. La couverture s’étend ; voir la feuille de route.

reason fournit des informations de diagnostic utiles pour déboguer l’intégration. Il ne change pas le sens de vulnerable.

Quand exécuter la vérification

Exécutez la vérification lorsqu’un utilisateur importe une phrase de récupération existante, une fois que le wallet a dérivé l’entropie BIP-39.

Hébergement personnalisé

Par défaut, le client récupère les buckets depuis l’hébergement public des datasets d’Unlukey. Passez une URL de base différente à check() pour utiliser un autre hébergement, comme votre propre CDN :

const result = await check(
  entropy,
  'https://your-cdn.example.com/unlukey-datasets'
)

Pour un contrôle total sur la façon dont les buckets du dataset sont récupérés, utilisez checkWith(entropy, readBucket) avec votre propre implémentation de readBucket(bits, prefixHex). Voir client/index.js dans le dépôt du SDK.

Tests en local

La CLI du dépôt du SDK est utile pour tester l’intégration sans construire d’interface :

node client/cli.js --remote 72039ecb02a3c880d4249e4b206933945a4f3a76ebaab26fa14e47a24e0f907e
# VULNERABLE

Consultez le README du dépôt du SDK pour générer un dataset d’exemple en local et tester le client avec.