@pasosdejesus/m 0.23.1 → 0.25.0

package/src/wallet/README.md

@@ -0,0 +1,119 @@
+# @pasosdejesus/m/wallet
+
+Núcleo compartido de billetera (`m/REQ/14`): mnemónica BIP39, derivación, firma,
+cifrado en reposo, almacenamiento intercambiable, provider EIP-1193 y verificación
+del usuario (WebAuthn). Sin React y sin Kysely: lo usan el CLI de `m` y los
+consumidores (learn.tg, sivel3, stable-sl).
+
+## Instalación
+
+Ya viene con `@pasosdejesus/m`. Los adaptadores de archivo viven en el subpath
+aparte para no arrastrar `node:fs` al bundle del navegador:
+
+```js
+import { createWallet, unlockWallet, signMessage, keccak } from '@pasosdejesus/m/wallet'
+import { FileStorage } from '@pasosdejesus/m/wallet/storage'   // Node.js
+```
+
+## Sin cifrado en reposo (primitivas)
+
+```js
+import { newMnemonic, accountFromMnemonic, privateKeyFromMnemonic, keccak } from '@pasosdejesus/m/wallet'
+
+const mnemonic = newMnemonic()
+const account = accountFromMnemonic(mnemonic)
+const privateKey = privateKeyFromMnemonic(mnemonic)   // 0x...
+const hash = keccak('hello')                          // reemplaza `cast keccak`
+```
+
+## Con cifrado en reposo (billetera in-app)
+
+```js
+import { createWallet, unlockWallet, lockWallet, signMessage } from '@pasosdejesus/m/wallet'
+import { FileStorage } from '@pasosdejesus/m/wallet/storage'
+
+const storage = new FileStorage('/path/wallet.json')   // o MemoryStorage/IndexedDBStorage
+const { walletInfo, mnemonic } = await createWallet({ password: 'correct horse', storage })
+await lockWallet()
+await unlockWallet('correct horse', storage)
+const signature = await signMessage('hola')
+```
+
+`PBKDF2-SHA256` (600.000 iteraciones de piso, calibradas al dispositivo) + `AES-256-GCM`.
+Registros viejos con menos iteraciones se re-cifran al desbloquear.
+
+## Provider EIP-1193 y proveedor inyectado
+
+```js
+import { getInAppWalletProvider, getExternalProvider } from '@pasosdejesus/m/wallet'
+
+const provider = getInAppWalletProvider({ rpcUrl: process.env.RPC_URL })  // null si está bloqueada
+const injected = getExternalProvider()   // EIP-6963 con respaldo window.ethereum
+```
+
+Para React, conecta el store con `useSyncExternalStore` usando
+`subscribeExternalProvider`/`getExternalProviderSnapshot`.
+
+## Namespaces configurables
+
+Un paquete compartido no debe escribir en el namespace de un consumidor:
+
+```js
+import { setWalletDbName } from '@pasosdejesus/m/wallet'
+import { setDestinationsPrefix } from '@pasosdejesus/m/wallet'
+import { setRpName } from '@pasosdejesus/m/wallet'
+
+setWalletDbName('learn-tg-pdj-wallet')             // IndexedDB (default: pasosdejesus-m-wallet)
+setDestinationsPrefix('learn.tg.pdj-wallet.')      // localStorage
+setRpName('learn.tg')                              // nombre de la credencial WebAuthn
+```
+
+## React (`./wallet/next`)
+
+Capa React de la billetera in-app (`m/REQ/37`, graduada de `learn.tg/packages/pdj-wallet-next`):
+
+```tsx
+import {
+  useInAppWallet, InAppWalletSetup, InAppWalletUnlock, configureInAppWallet,
+} from '@pasosdejesus/m/wallet/next'
+
+// Conserva tu namespace si ya tienes billeteras creadas:
+configureInAppWallet({
+  dbName: 'learn-tg-pdj-wallet',
+  destinationsPrefix: 'learn.tg.pdj-wallet.',
+  rpName: 'learn.tg',
+})
+
+// Textos: por defecto en/es; el host puede inyectar los suyos:
+<InAppWalletSetup lang="es" messages={{ createTitle: 'Abrir cartera' }} onDone={(a) => {}} />
+```
+
+`react` es un *optional peer*: el subpath está fuera del barrel, así que importar
+`@pasosdejesus/m/wallet` no arrastra React.
+
+## Pruebas
+
+Mocks en `@pasosdejesus/m/test-utils` (`installLocalStorage`, `installIndexedDB`,
+`mockWebAuthn`). `IndexedDBStorage` requiere la devDependency opcional
+`fake-indexeddb`.
+
+Preset listo para vitest (jsdom + mocks ya instalados):
+
+```ts
+// vitest.config.ts
+export default {
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['@pasosdejesus/m/test-utils/wallet-setup'],
+  },
+}
+```
+
+O a mano: `import { setupWalletTests } from '@pasosdejesus/m/test-utils'; setupWalletTests()`.
+
+## Notas
+
+- Fase 1/2 de `m/REQ/14`: primitivas, estado, storage, provider, WebAuthn (L1/L2),
+  destinos y resolutor EIP-6963. La capa React (hook + `InAppWalletSetup`/`InAppWalletUnlock`)
+  vive en el subpath `./wallet/next` (`m/REQ/37`).
+- E2E con firma real: `@pasosdejesus/m/e2e` (`injectEIP6963`, `setupFullWalletMock`).