@accesly/react 1.0.0-pre.1 → 1.0.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord } from '@accesly/core';
+import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord, EncryptedEnvelope } from '@accesly/core';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -444,6 +444,88 @@ declare class NotImplementedYetError extends Error {
  *      - Persiste new CredentialRecord local
  *      - Zero-iza la seed
  */
+interface ReconstructedSeed {
+    /** 32-byte ed25519 seed reconstruida vía Shamir(F2_recovery + F3). CALLER ZEROIZE. */
+    readonly privateSeed: Uint8Array;
+    /** 32-byte ed25519 public key derivada. */
+    readonly publicKey: Uint8Array;
+    /** 32-byte recoveryKey derivada del password — útil para re-cifrar F2'/F3' nuevos. */
+    readonly recoveryKey: Uint8Array;
+    /** Base64 32-byte salt que vino del backend. */
+    readonly recoverySalt: string;
+}
+/**
+ * Input para `recovery.finalize(...)` — orquestador end-to-end de la rotación
+ * de signers tras una recuperación por OTP.
+ *
+ * El caller debe pre-cumplir 2 pasos UI:
+ *   a) `reconstructSeed(...)` — devolvió `privateSeed` (la VIEJA, va a firmar
+ *      la auth entry) + `publicKey` (la VIEJA, no se rota acá).
+ *   b) WebAuthn `navigator.credentials.create()` con PRF extension — devolvió
+ *      `credentialId`, `secp256r1Pubkey`, y un output PRF que el caller
+ *      derivó en 2 keys `newF1Key` + `newF2Key` (HKDF típicamente).
+ *
+ * El SDK hace todo lo demás client-side:
+ *   1. Genera fresh ed25519 seed (la NUEVA) + Shamir 2-of-3 split.
+ *   2. Cifra F1' con `newF1Key`, F2' con `newF2Key`, F3' con `recoveryKey`.
+ *   3. Cifra una segunda copia de F2' con `recoveryKey` (F2_recovery) para
+ *      que la siguiente recovery siga siendo posible.
+ *   4. POST /recovery/simulate-rotate-signer → backend simula + devuelve material.
+ *   5. Firma la auth entry con la SEED VIEJA contra la regla `admin-cfg`.
+ *   6. POST /recovery/finalize con auth entry firmada + new fragments.
+ *   7. Persiste el nuevo `CredentialRecord` en `DeviceStore` (sustituye el viejo).
+ *   8. Zeroiza todas las llaves intermedias (la seed vieja la entrega el caller,
+ *      su lifecycle es responsabilidad del caller).
+ */
+interface FinalizeRecoveryInput {
+    /** Email del usuario (case-insensitive, se normaliza). */
+    readonly email: string;
+    /**
+     * Password de Cognito (UTF-8 bytes). El SDK la usa SOLO para derivar el
+     * `newRecoveryKey` con `PBKDF2(password, newRecoverySalt, 600k)`. Caller
+     * debe zeroizar tras la llamada.
+     */
+    readonly cognitoPassword: Uint8Array;
+    /** Token KMS-HMAC que devolvió `verifyOtp()` — TTL 5min. */
+    readonly recoveryJwt: string;
+    /**
+     * La seed VIEJA reconstruida por `reconstructSeed()`. Se usa SOLO para
+     * firmar la `SorobanAuthorizationEntry` de `rotate_signer` (la regla
+     * `admin-cfg` valida con el ed25519 pubkey actual del Smart Account, que
+     * es el del owner viejo). Tras firmar, el SDK la zeroiza internamente.
+     *
+     * IMPORTANTE: pasa `seedResult.privateSeed` tal cual te lo dio
+     * `reconstructSeed()`. Si ya lo zeroizaste, falla.
+     */
+    readonly oldReconstructedSeed: Uint8Array;
+    /**
+     * La pubkey VIEJA (32 bytes) — derivable de `oldReconstructedSeed`, pero
+     * la pedimos explícita para sanity-check y para empaquetar dentro del
+     * `Signer::External(verifier, pubkey)` del AuthPayload.
+     */
+    readonly oldOwnerPubkey: Uint8Array;
+    /** Credential ID del nuevo passkey (de `navigator.credentials.create`). */
+    readonly newCredentialId: Uint8Array;
+    /** Pubkey secp256r1 uncompressed (65 bytes) del nuevo passkey. */
+    readonly newSecp256r1Pubkey: Uint8Array;
+    /** Salt PRF del nuevo passkey (32 bytes random). */
+    readonly newPrfSalt: Uint8Array;
+    /** AES-256 key derivada del PRF output para cifrar F1'. */
+    readonly newF1Key: Uint8Array;
+    /** AES-256 key derivada del PRF output para cifrar F2' (PRF-bound, sign path). */
+    readonly newF2Key: Uint8Array;
+    /** Salt aleatorio (32 bytes) para el nuevo emailCommitment. */
+    readonly newEmailSalt: Uint8Array;
+}
+interface FinalizeRecoveryResult {
+    readonly walletAddress: string;
+    readonly txHash: string;
+    readonly status: string;
+    /** Pubkey ed25519 NUEVA (32 bytes). Útil para UI confirmación. */
+    readonly newPublicKey: Uint8Array;
+    /** Link al explorer. */
+    readonly explorerUrl: string;
+}
 interface RecoveryNamespace {
     /** Pide OTP. Backend rate-limita; el caller debe respetar `cooldownSeconds`. */
     requestOtp(input: {
@@ -461,19 +543,42 @@ interface RecoveryNamespace {
         expiresAt: number;
     }>;
     /**
-     * Cierra el flujo de recovery. Tras éxito el `walletAddress` rotó sus
-     * signers on-chain y el dispositivo nuevo tiene los fragmentos
-     * persistidos. Pasar el password de Cognito en plano (UTF-8).
+     * Descarga `/fragments/3`, descifra F2_recovery + F3 con la `recoveryKey`
+     * derivada del password y reconstruye la seed via Shamir.
+     *
+     * El caller DEBE zero-izar `result.privateSeed` y `result.recoveryKey`
+     * tras firmar la rotación + cifrar las nuevas F1'/F2'/F3'.
      *
-     * El caller es responsable de zeroizar `cognitoPassword` después.
+     * El caller también es responsable de zeroizar `cognitoPassword` después.
      */
-    finalize(input: {
-        email: string;
+    reconstructSeed(input: {
         cognitoPassword: Uint8Array;
         recoveryJwt: string;
+    }): Promise<ReconstructedSeed>;
+    /**
+     * Orquestador completo de la rotación de signers para Recovery v2.
+     * Ver `FinalizeRecoveryInput` para los pre-requisitos.
+     */
+    finalize(input: FinalizeRecoveryInput): Promise<FinalizeRecoveryResult>;
+    /**
+     * Bajo nivel: submitea la rotación al backend tras que el caller haya
+     * armado el body manualmente. `finalize(...)` es el wrapper recomendado.
+     */
+    submitFinalize(input: {
+        recoveryJwt: string;
+        unsignedXdr: string;
+        signedAuthEntryXdr: string;
+        newSecp256r1Pubkey: string;
+        newFragmentF1Encrypted: EncryptedEnvelope;
+        newFragmentF2Encrypted: EncryptedEnvelope;
+        newFragmentF2Recovery: EncryptedEnvelope;
+        newFragmentF3Encrypted: EncryptedEnvelope;
+        newRecoverySalt: string;
+        newEmailCommitment: string;
     }): Promise<{
         walletAddress: string;
         txHash: string;
+        status: string;
     }>;
 }
 interface AcceslyHook {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { CognitoAuthClient, InMemorySessionStorage, InMemoryDeviceStore, TokenManager, AccesslyApiClient, AccesslyEndpoints, normalizeSecp256r1Pubkey, createWallet, generateRecoverySalt, decryptAesGcm, deriveRecoveryKey, encryptAesGcm, emailHashBytes, computeSmartAccountAddress, signTransaction, generateX25519Keypair, unwrapSessionFragment2, reconstructFromPlainAndEncrypted, signSorobanAuthEntry, AccesslyApiError } from '@accesly/core';
+import { CognitoAuthClient, InMemorySessionStorage, InMemoryDeviceStore, TokenManager, AccesslyApiClient, AccesslyEndpoints, normalizeSecp256r1Pubkey, createWallet, generateRecoverySalt, decryptAesGcm, deriveRecoveryKey, encryptAesGcm, emailHashBytes, computeSmartAccountAddress, signTransaction, generateX25519Keypair, unwrapSessionFragment2, reconstructFromPlainAndEncrypted, signSorobanAuthEntry, reconstructKey, AccesslyApiError } from '@accesly/core';
 import { createContext, useMemo, useState, useRef, useEffect, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
@@ -190,6 +190,7 @@ function useAccesly() {
         secp256r1Pubkey: hexFromBytes(params.secp256r1Pubkey),
         fragmentF2: encodeFragmentToWire(params.fragmentF2),
         fragmentF3: encodeFragmentToWire(params.fragmentF3),
+        ...params.fragmentF2Recovery ? { fragmentF2Recovery: encodeFragmentToWire(params.fragmentF2Recovery) } : {},
         ...params.emailHash ? { emailHash: params.emailHash } : {},
         ...params.recoverySalt ? { recoverySalt: params.recoverySalt } : {}
       });
@@ -273,18 +274,22 @@ function useAccesly() {
           encryptionKeys: input.encryptionKeys
         });
         let fragmentF3ToSend = created.encryptedFragments[2];
+        let fragmentF2Recovery;
         let recoverySaltBase64;
         if (input.cognitoPassword) {
           const recoverySalt = generateRecoverySalt();
+          const f2Plain = decryptAesGcm(created.encryptedFragments[1], input.encryptionKeys[1]);
           const f3Plain = decryptAesGcm(created.encryptedFragments[2], input.encryptionKeys[2]);
           const recoveryKey = deriveRecoveryKey({
             password: input.cognitoPassword,
             salt: recoverySalt
           });
           try {
+            fragmentF2Recovery = encryptAesGcm(f2Plain, recoveryKey);
             fragmentF3ToSend = encryptAesGcm(f3Plain, recoveryKey);
           } finally {
             for (let i = 0; i < recoveryKey.length; i += 1) recoveryKey[i] = 0;
+            for (let i = 0; i < f2Plain.length; i += 1) f2Plain[i] = 0;
             for (let i = 0; i < f3Plain.length; i += 1) f3Plain[i] = 0;
           }
           recoverySaltBase64 = base64FromBytes(recoverySalt);
@@ -324,6 +329,7 @@ function useAccesly() {
             fragmentF2: created.encryptedFragments[1],
             fragmentF3: fragmentF3ToSend,
             emailHash: emailHashHex,
+            ...fragmentF2Recovery ? { fragmentF2Recovery } : {},
             ...recoverySaltBase64 ? { recoverySalt: recoverySaltBase64 } : {}
           });
         } catch (err) {
@@ -533,11 +539,147 @@ function useAccesly() {
       async verifyOtp(input) {
         return ctx.endpoints.verifyRecoveryOtp(input);
       },
-      async finalize(_input) {
-        throw new NotImplementedYetError("recovery", "finalize");
+      async reconstructSeed(input) {
+        const frag = await ctx.endpoints.getFragment3(input.recoveryJwt);
+        if (!frag.fragmentF2Recovery) {
+          throw new Error(
+            "recovery.reconstructSeed: la wallet fue creada antes de Fase 1 y no tiene F2 cipher-bound a recoveryKey. No es recuperable v\xEDa OTP."
+          );
+        }
+        const recoverySalt = base64ToBytes(frag.recoverySalt);
+        const recoveryKey = deriveRecoveryKey({
+          password: input.cognitoPassword,
+          salt: recoverySalt
+        });
+        const f2Envelope = {
+          ciphertext: base64ToBytes(frag.fragmentF2Recovery.ciphertext),
+          nonce: base64ToBytes(frag.fragmentF2Recovery.nonce)
+        };
+        const f3Envelope = {
+          ciphertext: base64ToBytes(frag.fragmentF3Encrypted.ciphertext),
+          nonce: base64ToBytes(frag.fragmentF3Encrypted.nonce)
+        };
+        const seedResult = reconstructKey({
+          fragments: [
+            { envelope: f2Envelope, key: recoveryKey },
+            { envelope: f3Envelope, key: recoveryKey }
+          ]
+        });
+        return {
+          privateSeed: seedResult.privateSeed,
+          publicKey: seedResult.publicKey,
+          recoveryKey,
+          recoverySalt: frag.recoverySalt
+        };
+      },
+      async finalize(input) {
+        const networkPassphrase = stellarConfig.networkPassphrase;
+        const verifierAddress = stellarConfig.ed25519VerifierAddress;
+        const explorerBase = networkPassphrase === "Public Global Stellar Network ; September 2015" ? "https://stellar.expert/explorer/public/tx/" : "https://stellar.expert/explorer/testnet/tx/";
+        if (input.oldReconstructedSeed.length !== 32) {
+          throw new Error(
+            `recovery.finalize: oldReconstructedSeed must be 32 bytes, got ${input.oldReconstructedSeed.length}`
+          );
+        }
+        if (input.oldOwnerPubkey.length !== 32) {
+          throw new Error(
+            `recovery.finalize: oldOwnerPubkey must be 32 bytes, got ${input.oldOwnerPubkey.length}`
+          );
+        }
+        if (input.newSecp256r1Pubkey.length !== 65) {
+          throw new Error(
+            `recovery.finalize: newSecp256r1Pubkey must be 65 bytes (uncompressed), got ${input.newSecp256r1Pubkey.length}`
+          );
+        }
+        const newRecoverySalt = generateRecoverySalt();
+        const newRecoveryKey = deriveRecoveryKey({
+          password: input.cognitoPassword,
+          salt: newRecoverySalt
+        });
+        const newRecoverySaltBase64 = base64FromBytes(newRecoverySalt);
+        const created = createWallet({
+          emailBytes: new TextEncoder().encode(input.email),
+          emailSalt: input.newEmailSalt,
+          encryptionKeys: [input.newF1Key, input.newF2Key, newRecoveryKey]
+        });
+        const f2PlainShare = decryptAesGcm(created.encryptedFragments[1], input.newF2Key);
+        let newFragmentF2Recovery;
+        try {
+          newFragmentF2Recovery = encryptAesGcm(f2PlainShare, newRecoveryKey);
+        } finally {
+          for (let i = 0; i < f2PlainShare.length; i += 1) f2PlainShare[i] = 0;
+        }
+        const newSecp256r1Canonical = normalizeSecp256r1Pubkey(input.newSecp256r1Pubkey);
+        const newOwnerHex = hexFromBytes(created.publicKey);
+        const newSecpHex = hexFromBytes(newSecp256r1Canonical);
+        const newEmailCommitHex = hexFromBytes(created.emailCommitment);
+        const sim = await ctx.endpoints.simulateRotateSigner(input.recoveryJwt, {
+          newOwnerEd25519Pubkey: newOwnerHex,
+          newSecp256r1Pubkey: newSecpHex,
+          newEmailCommitment: newEmailCommitHex
+        });
+        const { signedAuthEntryXdr } = await signSorobanAuthEntry({
+          signaturePayloadHashBase64: sim.signaturePayloadHashBase64,
+          contextRuleIds: [...sim.contextRuleIds],
+          placeholderAuthEntryXdr: sim.placeholderAuthEntryXdr,
+          ed25519Seed: input.oldReconstructedSeed,
+          ed25519VerifierAddress: verifierAddress,
+          ownerPubkey: input.oldOwnerPubkey
+        });
+        let finalize;
+        try {
+          finalize = await ctx.endpoints.finalizeRecovery(input.recoveryJwt, {
+            unsignedXdr: sim.unsignedXdr,
+            signedAuthEntryXdr,
+            newSecp256r1Pubkey: newSecpHex,
+            newFragmentF1Encrypted: encodeFragmentToWire(created.encryptedFragments[0]),
+            newFragmentF2Encrypted: encodeFragmentToWire(created.encryptedFragments[1]),
+            newFragmentF2Recovery: encodeFragmentToWire(newFragmentF2Recovery),
+            newFragmentF3Encrypted: encodeFragmentToWire(created.encryptedFragments[2]),
+            newRecoverySalt: newRecoverySaltBase64,
+            newEmailCommitment: newEmailCommitHex
+          });
+        } finally {
+          for (let i = 0; i < newRecoveryKey.length; i += 1) newRecoveryKey[i] = 0;
+        }
+        await ctx.deviceStore.saveCredential({
+          username: input.email,
+          credentialId: input.newCredentialId,
+          secp256r1Pubkey: newSecp256r1Canonical,
+          fragmentF1Encrypted: created.encryptedFragments[0],
+          fragmentF2Encrypted: created.encryptedFragments[1],
+          fragmentF3Encrypted: created.encryptedFragments[2],
+          publicKey: created.publicKey,
+          emailCommitment: created.emailCommitment,
+          prfSalt: input.newPrfSalt,
+          fallbackKeyMaterial: new Uint8Array(0),
+          walletAddress: finalize.walletAddress,
+          onChain: true,
+          createdAt: Date.now()
+        });
+        return {
+          walletAddress: finalize.walletAddress,
+          txHash: finalize.txHash,
+          status: finalize.status,
+          newPublicKey: created.publicKey,
+          explorerUrl: `${explorerBase}${finalize.txHash}`
+        };
+      },
+      async submitFinalize(input) {
+        return ctx.endpoints.finalizeRecovery(input.recoveryJwt, {
+          unsignedXdr: input.unsignedXdr,
+          signedAuthEntryXdr: input.signedAuthEntryXdr,
+          newSecp256r1Pubkey: input.newSecp256r1Pubkey,
+          newFragmentF1Encrypted: encodeFragmentToWire(input.newFragmentF1Encrypted),
+          newFragmentF2Encrypted: encodeFragmentToWire(input.newFragmentF2Encrypted),
+          newFragmentF2Recovery: encodeFragmentToWire(input.newFragmentF2Recovery),
+          newFragmentF3Encrypted: encodeFragmentToWire(input.newFragmentF3Encrypted),
+          newRecoverySalt: input.newRecoverySalt,
+          newEmailCommitment: input.newEmailCommitment
+        });
       }
     }),
-    [ctx]
+    [ctx, stellarConfig, hexFromBytes]
   );
   const session = useMemo(
     () => ({