@accesly/react 1.1.2 → 1.2.0

package/dist/index.d.cts

@@ -0,0 +1,835 @@
+import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord, EncryptedEnvelope } from '@accesly/core';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * `AcceslyProvider` — top-level React provider that creates the SDK instances
+ * once and exposes them through context. All hooks consume this.
+ *
+ * Apps wrap their tree:
+ *   <AcceslyProvider appId="myapp" env="dev">
+ *     <App />
+ *   </AcceslyProvider>
+ *
+ * For advanced cases (custom IdP, custom storage), pass `overrides` to inject
+ * your own `AuthClient`, `SessionStorage`, or `DeviceStore`.
+ */
+
+interface AcceslyProviderProps {
+    readonly appId: string;
+    readonly env: Environment;
+    readonly children: ReactNode;
+    /** Override the resolved API URL. */
+    readonly apiUrl?: string;
+    /** Override the resolved Cognito config. */
+    readonly cognitoConfig?: CognitoConfig;
+    /** Override SDK pieces — for tests or custom backends. */
+    readonly overrides?: {
+        readonly authClient?: AuthClient;
+        readonly sessionStorage?: SessionStorage;
+        readonly deviceStore?: DeviceStore;
+    };
+    /** Optional telemetry sink — surfaces every API request/response/retry. */
+    readonly telemetry?: TelemetrySink;
+}
+declare function AcceslyProvider(props: AcceslyProviderProps): JSX.Element;
+
+interface AcceslyContextValue {
+    readonly appId: string;
+    readonly env: Environment;
+    readonly apiUrl: string;
+    readonly cognitoConfig: CognitoConfig;
+    readonly authClient: AuthClient;
+    readonly sessionStorage: SessionStorage;
+    readonly tokenManager: TokenManager;
+    readonly endpoints: AccesslyEndpoints;
+    readonly deviceStore: DeviceStore;
+    /** Current auth status — re-rendered whenever it changes. */
+    readonly status: AuthStatus;
+    readonly username: string | null;
+    /** Force a re-read of `tokenManager.getStatus()`. */
+    readonly refreshStatus: () => Promise<void>;
+}
+declare const AcceslyContext: react.Context<AcceslyContextValue | null>;
+
+/**
+ * Per-environment defaults — currently the only public stage is `dev`. The
+ * others are placeholders so the SDK API doesn't change when `staging`/`prod`
+ * come online (Fase 7+ / Fase 10).
+ */
+
+interface EnvironmentDefaults {
+    readonly apiUrl: string;
+    /**
+     * Lambda Function URL del `wallet-stream` Lambda — Server-Sent Events
+     * que multiplexa status + balance + activity en una sola conexión.
+     * Si está vacío, los hooks `useBalance` / `useWalletActivity` /
+     * `useWalletStatus` caen al polling fallback (mucho menos eficiente).
+     */
+    readonly walletStreamUrl: string;
+    readonly cognito: CognitoConfig;
+    readonly stellar: {
+        readonly networkPassphrase: string;
+        readonly horizonUrl: string;
+        readonly sorobanRpcUrl: string;
+        /**
+         * Stellar G-address of the account that invokes `CreateContract` for new
+         * Smart Accounts. Same account the backend Lambda uses, so the wallet
+         * address computed client-side via `wallet.computeAddress` matches
+         * exactly what the backend will (or did) deploy.
+         */
+        readonly deployerAddress: string;
+        /**
+         * Address del contrato `ed25519-verifier` desplegado en la red. Necesario
+         * cuando el SDK construye la entrada `Signer::External(verifier, pubkey)`
+         * dentro del `AuthPayload` que firma — el Smart Account compara con la
+         * misma address que tiene almacenada en su context rule.
+         */
+        readonly ed25519VerifierAddress: string;
+    };
+}
+declare const ENVIRONMENT_DEFAULTS: Record<Environment, EnvironmentDefaults>;
+
+/**
+ * `useAccesly()` — single hook with namespaces:
+ *   - auth   — signUp / confirmSignUp / signIn / signOut / status
+ *   - wallet — createWallet, getStoredWallet
+ *   - tx     — sendPayment, signRawXdr
+ *   - kyc    — start, status
+ *
+ * The hook returns stable references when the underlying SDK instances don't
+ * change. Each namespace is built lazily (memoised) so apps that only use
+ * `auth` don't bring `wallet` into their render.
+ */
+
+interface AuthNamespace {
+    readonly status: AuthStatus;
+    readonly username: string | null;
+    signUp(email: string, password: string): Promise<{
+        userSub: string;
+        userConfirmed: boolean;
+    }>;
+    confirmSignUp(email: string, code: string): Promise<void>;
+    resendConfirmation(email: string): Promise<void>;
+    signIn(email: string, password: string): Promise<void>;
+    signOut(): Promise<void>;
+}
+interface CreateWalletInput {
+    readonly email: string;
+    readonly emailSalt: Uint8Array;
+    readonly encryptionKeys: readonly [Uint8Array, Uint8Array, Uint8Array];
+    readonly secp256r1Pubkey: Uint8Array;
+    /**
+     * Optional. When provided together with `prfSalt`, the SDK persists a
+     * `CredentialRecord` to the configured `DeviceStore` BEFORE calling
+     * `POST /wallets`. That way, if the network request fails (timeout, tab
+     * close, etc.) the encrypted F1 shard + passkey metadata survive locally
+     * and the wallet can be recovered via `wallet.ensureWallet` on the next
+     * session (the backend dedupes by Cognito user → returns the same
+     * walletAddress).
+     *
+     * Pass it. Omitting it means an orphaned wallet on POST failure is
+     * unrecoverable without a server-side query.
+     */
+    readonly credentialId?: Uint8Array;
+    /** Optional. See `credentialId`. */
+    readonly prfSalt?: Uint8Array;
+    /**
+     * Password de Cognito en plano (`Uint8Array` codificado UTF-8).
+     *
+     * Recovery v2 (Fase 1, 2026-06-15): si se provee, el SDK deriva
+     * `recoveryKey = PBKDF2(password, recoverySalt, 600k)` y la usa para
+     * cifrar F3 antes de enviarlo al backend, en vez de usar
+     * `encryptionKeys[2]`. El backend almacena F3 cifrado con esa key —
+     * SOLO descifrable client-side con el mismo password.
+     *
+     * Sin esta prop el wallet se crea pero NO podrá recuperarse vía OTP
+     * (F3 quedará cifrado con `encryptionKeys[2]`, igual que en 0.x).
+     *
+     * El caller es responsable de zeroizar este buffer tras `createWallet`
+     * (el SDK no lo retiene en memoria).
+     */
+    readonly cognitoPassword?: Uint8Array;
+    /**
+     * 32-byte salt para HKDF — si se persiste en el `CredentialRecord`,
+     * `wallet.unlockForSigning` lo recupera y re-deriva las mismas keys sin
+     * intervención del caller. Si se omite, el SDK genera uno random y lo
+     * persiste igualmente. Si la wallet ya existe en el `DeviceStore` con un
+     * `encryptionSalt`, este input se ignora a favor del salt persistido (para
+     * preservar la decriptabilidad de F1).
+     */
+    readonly encryptionSalt?: Uint8Array;
+}
+interface CreatedWalletInfo {
+    readonly walletAddress: string;
+    readonly publicKey: Uint8Array;
+    /**
+     * `'on-chain'` if the backend confirmed deploy; `'pending-deploy'` if the
+     * backend submitted to Soroban but the contract did not land (typically
+     * because the Smart Account constructor exceeds Soroban v26 resource caps
+     * — Phase 1 territory). When pending, the `walletAddress` is the
+     * client-side-predicted address: same address that will be live once the
+     * deploy succeeds (idempotent on the backend).
+     */
+    readonly status: WalletStatus;
+    /** When `status === 'pending-deploy'`, the backend's reason if available. */
+    readonly pendingReason?: string;
+}
+
+type WalletStatus = 
+/** Backend confirmed the contract is live on Soroban. Ready to use. */
+'on-chain'
+/**
+ * Wallet record exists (locally and/or on backend) but the contract has NOT
+ * been observed on Soroban yet. Either deploy is still in flight, or
+ * landed in a ghost state. Re-run `wallet.ensureWallet` later (or call
+ * `wallet.retryDeploy(username)`).
+ */
+ | 'pending-deploy'
+/**
+ * Backend has the record but its Soroban RPC check did not respond — the
+ * SDK treats the address as usable but flags the uncertainty.
+ */
+ | 'unknown';
+interface EnsureWalletResult {
+    readonly walletAddress: string;
+    readonly status: WalletStatus;
+    /** True if this call generated a new keypair (first-time deploy path). */
+    readonly createdNow: boolean;
+    /** Present only when `createdNow === true`. */
+    readonly publicKey?: Uint8Array;
+}
+interface RemoteWalletInfo {
+    readonly walletAddress: string;
+    readonly appId: string;
+    readonly createdAt: string;
+    readonly onChain: boolean | null;
+}
+interface RetryDeployResult {
+    readonly walletAddress: string;
+    readonly status: WalletStatus;
+}
+/**
+ * Input para `wallet.bootstrap(...)` — el high-level "todo en uno" que cualquier
+ * integrador típico va a llamar como entry point. Hace **TODO**:
+ *
+ *   1. `sha256(email)` → userId opaco para el RP.
+ *   2. Genera `prfSalt` aleatorio (32 bytes).
+ *   3. `registerPasskey(...)` con extensión PRF — pide huella/face/Hello.
+ *   4. Genera `encryptionSalt` aleatorio (32 bytes).
+ *   5. HKDF(prfOutput, encryptionSalt, "accesly-{f1,f2,f3}-encryption") → 3 keys AES.
+ *   6. Genera `emailSalt` aleatorio (32 bytes).
+ *   7. `wallet.ensureWallet(...)` — el flujo idempotente get-or-create.
+ *   8. Persiste `encryptionSalt` en `CredentialRecord` para que `unlockForSigning`
+ *      pueda re-derivar las mismas keys.
+ *   9. Zeroiza `prfOutput`, `f1Key`, `f2Key`, `f3Key`, `cognitoPasswordBytes`.
+ *
+ * Después de `bootstrap`, llamá `tx.send(...)` directamente con
+ * `wallet.unlockForSigning(email)` — no hace falta más wiring.
+ */
+interface BootstrapWalletInput {
+    readonly email: string;
+    /**
+     * Password de Cognito en plano. Usado para:
+     *  - Re-cifrar F3 (y F2_recovery) con `recoveryKey = PBKDF2(password,
+     *    recoverySalt, 600k)` para el flujo de Recovery v2.
+     *
+     * El SDK lo zeroiza tras el ensureWallet.
+     */
+    readonly password: string;
+    /**
+     * Overrides opcionales para el `registerPasskey` interno. Caso típico:
+     * cambiar `rpName: 'MiApp'` para que el browser muestre tu marca en el
+     * prompt biométrico. `rpId` por default = `window.location.hostname`.
+     */
+    readonly passkey?: {
+        readonly rpId?: string;
+        readonly rpName?: string;
+    };
+}
+/**
+ * Material reconstruido por `wallet.unlockForSigning(...)` y listo para pasar
+ * a `tx.send(...)`. Las llaves se zeroizan tras la firma; el caller no debería
+ * retenerlas más allá del round-trip.
+ */
+interface UnlockedSigningMaterial {
+    /** F1 share desencriptado (Shamir-encoded blob). Lo zero-iza `tx.send`. */
+    readonly fragmentF1Plain: Uint8Array;
+    /** AES key con la que el SDK desencripta el envelope F2 del backend. */
+    readonly fragmentF2Key: Uint8Array;
+    /** Pubkey ed25519 del owner del Smart Account (32 bytes). */
+    readonly ownerPubkey: Uint8Array;
+    /** Address C… del Smart Account (display only). */
+    readonly walletAddress: string;
+}
+interface WalletNamespace {
+    /**
+     * **Entry-point recomendado.** Registra passkey + deriva keys + crea-o-recupera
+     * wallet en una sola llamada. Sustituye al patrón histórico de
+     * `ensureWalletWithPasskey` que tenía que copiar-pegar cada integrador.
+     *
+     * Idempotente: si ya hay wallet en el backend para este Cognito user, devuelve
+     * `{createdNow: false}` sin re-registrar passkey. Si no, hace el flow completo.
+     */
+    bootstrap(input: BootstrapWalletInput): Promise<EnsureWalletResult>;
+    /**
+     * **Helper para `tx.send`.** Lee la credencial del DeviceStore, abre el
+     * passkey via WebAuthn (PIN/biométrico), re-deriva las AES keys con HKDF, y
+     * descifra F1 local. Devuelve los 3 materiales que `tx.send` necesita.
+     *
+     * Lanza con mensaje claro si:
+     *  - no hay credential local (el user tiene que correr `recovery.finalize`
+     *    en este device);
+     *  - el passkey no devolvió PRF (browser sin soporte);
+     *  - el envelope F1 falla al descifrar (corrupto / passkey distinto).
+     */
+    unlockForSigning(username: string): Promise<UnlockedSigningMaterial>;
+    /**
+     * End-to-end wallet creation:
+     *  1. Generate keypair + Shamir split + encrypt fragments (client-side).
+     *  2. Compute the Smart Account address client-side from the ed25519
+     *     pubkey + the env-configured deployer (deterministic — matches what
+     *     the backend will deploy).
+     *  3. If `credentialId` + `prfSalt` were provided, persist a full
+     *     `CredentialRecord` (with all 3 encrypted fragments + computed
+     *     walletAddress + `onChain: null`) to the `DeviceStore` BEFORE the
+     *     network call — crash-safety + retry capability in one step.
+     *  4. POST /wallets with hex pubkeys + base64 fragments.
+     *  5. On success, mark the record `onChain: true` (cleared by the next
+     *     `ensureWallet` call which queries Soroban via the backend).
+     *
+     * The caller is responsible for the encryption-key derivation (typically
+     * via WebAuthn PRF).
+     */
+    createWallet(input: CreateWalletInput): Promise<CreatedWalletInfo>;
+    /**
+     * Idempotent wallet bootstrap. The recommended entry-point at the top of
+     * every authenticated session:
+     *
+     *  - `GET /wallets` → if `onChain === true`, returns `{ status: 'on-chain' }`
+     *    and skips keypair generation entirely.
+     *  - `GET /wallets` → if `onChain === false`, calls `retryDeploy` to
+     *    re-submit the existing record (idempotent on the backend) and
+     *    returns `{ status: 'pending-deploy' }` if the retry didn't surface
+     *    success yet.
+     *  - `GET /wallets` → if `onChain === null` (Soroban RPC unreachable),
+     *    returns `{ status: 'unknown' }` — the address is usable but the
+     *    SDK couldn't confirm on-chain presence.
+     *  - `GET /wallets` → 404 → runs the full `createWallet` flow and returns
+     *    `{ status: 'pending-deploy', createdNow: true }`. Subsequent calls
+     *    will upgrade to `'on-chain'` once the backend's Soroban check passes.
+     */
+    ensureWallet(input: CreateWalletInput): Promise<EnsureWalletResult>;
+    /**
+     * Re-submits `POST /wallets` for an existing local `CredentialRecord`. Used
+     * to recover from ghost wallets (record exists but deploy did not land).
+     * Requires the record to have been persisted with `fragmentF2Encrypted`,
+     * `fragmentF3Encrypted`, `publicKey`, and `emailCommitment` (which
+     * `createWallet` does automatically when `credentialId` + `prfSalt` are
+     * provided).
+     *
+     * Backend dedupes by ownerPubkey — the returned address is guaranteed to
+     * equal the one originally stored.
+     */
+    retryDeploy(username: string): Promise<RetryDeployResult>;
+    /**
+     * Reads the user's wallet metadata from the backend. Returns null if the
+     * user has not yet created a wallet.
+     */
+    fetchRemote(): Promise<RemoteWalletInfo | null>;
+    /**
+     * Computes the deterministic Smart Account address that the backend will
+     * (or did) deploy for the given ed25519 owner pubkey. Same algorithm
+     * Stellar Core uses — pure client-side, no network call. Useful to show
+     * the address to the user instantly before any POST.
+     */
+    computeAddress(ownerPubkey: Uint8Array): Promise<string>;
+    /** Returns the locally-stored credential record, if any. */
+    getStoredCredential(username: string): Promise<CredentialRecord | null>;
+    /**
+     * Lists `CredentialRecord`s whose `walletAddress` is still `null` OR whose
+     * `onChain` flag is `false`. Diagnostic + recovery aid.
+     */
+    getPendingWallets(): Promise<readonly CredentialRecord[]>;
+    /** Removes a stored credential. Useful after a failed pending wallet is reconciled. */
+    clearStoredCredential(username: string): Promise<void>;
+    /**
+     * Testnet only — fondea el Smart Account con XLM via Stellar friendbot.
+     *
+     * Friendbot acepta directamente direcciones de contrato Soroban (`C…`):
+     * internamente arma una tx `invokeContract(XLM_SAC.transfer, ...)` desde
+     * la cuenta de la SDF y la submitea. Resultado: ~10,000 XLM testnet al
+     * Smart Account, sin necesidad de un G-account intermediario.
+     *
+     * Idempotente: el primer call exitoso marca `testnetFunded: true` en el
+     * `CredentialRecord` local; subsiguientes calls devuelven `alreadyFunded:
+     * true` sin hacer otro round-trip a friendbot.
+     *
+     * En `env: 'mainnet'` la función es un no-op (no existe friendbot en
+     * mainnet) y devuelve `{ funded: false, alreadyFunded: false, reason:
+     * 'mainnet-not-supported' }`. La UI tiene que mostrar opciones de onramp
+     * real (Etherfuse, MoonPay, transferencia externa).
+     *
+     * `ensureWallet` lo llama automáticamente fire-and-forget cuando el
+     * status final es `'on-chain'` — el caller solo necesita llamarlo
+     * explícitamente si quiere mostrar feedback en la UI durante el funding.
+     */
+    fundTestnet(walletAddress: string): Promise<FundTestnetResult>;
+}
+interface FundTestnetResult {
+    /** `true` si esta llamada disparó friendbot y fondeó la wallet ahora. */
+    readonly funded: boolean;
+    /**
+     * `true` si la wallet ya había sido fondeada antes (flag local o response
+     * de friendbot indicando que la cuenta ya existe). Igualmente válido —
+     * la UI puede mostrar "ya tienes XLM" sin pedir acción del user.
+     */
+    readonly alreadyFunded: boolean;
+    /** Texto explicativo para no-op cases (mainnet, missing record, etc.). */
+    readonly reason?: 'mainnet-not-supported' | 'friendbot-error' | 'already-funded' | 'funded-now';
+}
+/**
+ * Input para `tx.send(...)` — manda XLM desde el Smart Account del usuario a
+ * cualquier address Stellar (G… clásico o C… contrato).
+ *
+ * El SDK orquesta todo el flujo: simulate → ECDH F2 → reconstruct seed →
+ * sign auth entry → submit. El caller solo entrega los inputs sensibles que
+ * vienen de su flow de unlock (WebAuthn PRF + derivación de F2 key).
+ */
+interface SendXlmInput {
+    /** Destinatario. G… (clásico) o C… (contrato). */
+    readonly destinationAddress: string;
+    /** Monto en STROOPS (1 XLM = 10_000_000 stroops). Base-10 string para evitar precisión. */
+    readonly amountStroops: string;
+    /**
+     * F1 (Shamir share encoded incluyendo el byte de índice) ya en plano —
+     * típicamente desencriptado client-side via WebAuthn PRF antes de llamar.
+     * El SDK lo zero-iza tras combinar con F2.
+     */
+    readonly fragmentF1Plain: Uint8Array;
+    /**
+     * Llave AES-256 con la que el SDK desencripta el F2 envelope que vino
+     * del backend. La derivación de esta llave es responsabilidad del caller
+     * (usualmente PBKDF2 sobre material derivado de credenciales del user).
+     * Se zero-iza al terminar.
+     */
+    readonly fragmentF2Key: Uint8Array;
+    /**
+     * Pubkey ed25519 (32 bytes) del owner del Smart Account. Se usa para:
+     *   1) Sanity-check de que la seed reconstruida deriva esta pubkey.
+     *   2) Empaquetarla dentro del `Signer::External(verifier, pubkey)` del
+     *      AuthPayload.
+     */
+    readonly ownerPubkey: Uint8Array;
+}
+interface SendXlmResult {
+    readonly txHash: string;
+    readonly status: string;
+    readonly explorerUrl: string;
+}
+interface TxNamespace {
+    /**
+     * End-to-end XLM transfer desde el Smart Account del user.
+     *
+     * Flujo interno (no-custodial):
+     *   1) `POST /tx/simulate` con `{ amountStroops, destinationAddress }`.
+     *   2) Genera X25519 keypair efímero + `POST /fragments/2` con la pubkey.
+     *      Backend devuelve F2 wrapped en una capa session-key. El SDK la
+     *      descifra con ECDH + HKDF — la session key NO persiste en disco.
+     *   3) Desencripta el F2 envelope interno con `fragmentF2Key` → F2 plain.
+     *   4) Combina F1 + F2 vía Shamir → ed25519 seed (32 bytes).
+     *   5) Computa `auth_digest = sha256(signature_payload || rule_ids_xdr)`
+     *      y lo firma con la seed → 64-byte ed25519 sig.
+     *   6) Empaqueta el `AuthPayload {signers, context_rule_ids}` ScVal,
+     *      reemplaza `credentials.address.signature` en la placeholder entry.
+     *   7) `POST /tx/submit` con `{ unsignedXdr, signedAuthEntryXdr }`.
+     *   8) Devuelve `{ txHash, status, explorerUrl }`.
+     *
+     * Toda llave plana sale de scope tras la firma. Lanza si:
+     *   - El backend rechaza simulate/submit.
+     *   - La reconstrucción Shamir falla (fragmentos no compatibles).
+     *   - La pubkey derivada de la seed no matchea `ownerPubkey`.
+     */
+    send(input: SendXlmInput): Promise<SendXlmResult>;
+    /**
+     * Bajo nivel: firma un envelope Stellar ya construido con una seed ed25519
+     * dada. Útil para flows custom que arman la tx fuera del SDK.
+     */
+    signRawXdr(input: {
+        transactionXdr: string;
+        ed25519Seed: Uint8Array;
+        expectedPublicKey?: Uint8Array;
+    }): Promise<{
+        signedXdr: string;
+        publicKey: Uint8Array;
+    }>;
+}
+interface KycNamespace {
+    start(): Promise<{
+        customerId: string;
+        status: string;
+        hostedUrl: string | null;
+    }>;
+    status(): Promise<{
+        customerId: string;
+        status: string;
+        hostedUrl: string | null;
+    }>;
+}
+interface SessionNamespace {
+    /** Create a temporary session key for unattended low-value tx (Soroban policy). */
+    create(_opts: {
+        readonly ttlSeconds: number;
+        readonly maxAmountStroops: string;
+    }): Promise<never>;
+    /** Revoke a previously-created session key. */
+    revoke(_sessionKeyId: string): Promise<never>;
+}
+interface SettingsNamespace {
+    /** Add a new device's passkey to an existing wallet (multi-device). */
+    addDevice(_secp256r1Pubkey: Uint8Array): Promise<never>;
+    /** Remove a device's passkey from the wallet. */
+    removeDevice(_secp256r1Pubkey: Uint8Array): Promise<never>;
+    /** List all device passkeys registered for the wallet. */
+    listDevices(): Promise<never>;
+    /** Change the spending limit policy. */
+    updateSpendingLimit(_opts: {
+        readonly limitStroops: string;
+        readonly perDayStroops?: string;
+    }): Promise<never>;
+}
+interface YieldNamespace {
+    /** Invest USDC into CETES via Etherfuse (50/50 yield share with Accesly). */
+    invest(_amountUsdc: string): Promise<never>;
+    /** Redeem CETES tokens back into USDC. */
+    redeem(_amountTokens: string): Promise<never>;
+    /** Read the user's current yield position. */
+    position(): Promise<never>;
+}
+/**
+ * Stub thrown by every method in the `session`, `settings`, `yield`
+ * namespaces. These features are designed but not implemented in v0.1.0 —
+ * they unblock with the dashboard work in Fase 7 (`session`/`settings`) and
+ * with Etherfuse activation (`yield`).
+ */
+declare class NotImplementedYetError extends Error {
+    constructor(namespace: string, method: string);
+}
+/**
+ * Recovery v2 — OTP por email + password de Cognito (Fase 1, 2026-06-15).
+ *
+ * Flujo desde la UI:
+ *   1. `recovery.requestOtp({ email })` → manda el OTP por SES.
+ *   2. `recovery.verifyOtp({ email, code })` → devuelve `recoveryJwt`.
+ *   3. `recovery.finalize({ email, password, recoveryJwt })` orquesta todo:
+ *      - GET /fragments/3 con el JWT
+ *      - Deriva recoveryKey con el password + recoverySalt del backend
+ *      - Decifra F3
+ *      - Decifra F2 (vía session key ECDH)
+ *      - Combina F2+F3 → seed ed25519 reconstruida
+ *      - Genera new passkey + new Shamir split (F1', F2', F3')
+ *      - Re-cifra F3' con la misma recoveryKey + nuevo salt
+ *      - Firma la tx `rotate_signer` localmente
+ *      - POST /recovery/finalize con todo
+ *      - 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**. El integrador
+ * solo provee email + password + recoveryJwt; el SDK hace TODO el resto:
+ *
+ *   1. `reconstructSeed(...)` con el password → seed VIEJA + recoveryKey.
+ *   2. `registerPasskey(...)` con PRF → nuevo credentialId + secp256r1Pubkey + prfOutput.
+ *   3. HKDF(prfOutput, encryptionSalt, "accesly-{f1,f2}-encryption") → newF1Key + newF2Key.
+ *   4. Genera new ed25519 seed + Shamir 2-of-3 + cifra F1'/F2' con PRF keys, F3' con recoveryKey.
+ *   5. `POST /recovery/simulate-rotate-signer` → backend arma + simula.
+ *   6. Firma `SorobanAuthorizationEntry` con la SEED VIEJA contra `admin-cfg`.
+ *   7. `POST /recovery/finalize` con auth entry firmada + new fragments.
+ *   8. Persiste new `CredentialRecord` (con `encryptionSalt`) en `DeviceStore`.
+ *   9. Zeroiza TODAS las llaves intermedias (privateSeed vieja, recoveryKey, PRF output, password).
+ */
+interface FinalizeRecoveryInput {
+    /** Email del usuario (case-insensitive, se normaliza). */
+    readonly email: string;
+    /**
+     * Password de Cognito (string). El SDK lo encoda a UTF-8 internamente y lo
+     * zeroiza tras la operación. No retengas referencias.
+     */
+    readonly password: string;
+    /** Token KMS-HMAC que devolvió `verifyOtp()` — TTL 5min. */
+    readonly recoveryJwt: string;
+    /**
+     * Overrides opcionales para el `registerPasskey` interno (mismo shape que
+     * `wallet.bootstrap`). Caso típico: `rpName: 'MiApp'`.
+     */
+    readonly passkey?: {
+        readonly rpId?: string;
+        readonly rpName?: string;
+    };
+}
+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: {
+        email: string;
+    }): Promise<{
+        cooldownSeconds: number;
+        expiresInSeconds: number;
+    }>;
+    /** Verifica OTP. Devuelve `recoveryJwt` con TTL 5min. */
+    verifyOtp(input: {
+        email: string;
+        code: string;
+    }): Promise<{
+        recoveryJwt: string;
+        expiresAt: number;
+    }>;
+    /**
+     * 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 también es responsable de zeroizar `cognitoPassword` después.
+     */
+    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;
+        newOwnerEd25519Pubkey: string;
+        newSecp256r1Pubkey: string;
+        newFragmentF1Encrypted: EncryptedEnvelope;
+        newFragmentF2Encrypted: EncryptedEnvelope;
+        newFragmentF2Recovery: EncryptedEnvelope;
+        newFragmentF3Encrypted: EncryptedEnvelope;
+        newRecoverySalt: string;
+        newEmailCommitment: string;
+    }): Promise<{
+        walletAddress: string;
+        txHash: string;
+        status: string;
+    }>;
+}
+interface AcceslyHook {
+    readonly auth: AuthNamespace;
+    readonly wallet: WalletNamespace;
+    readonly tx: TxNamespace;
+    readonly kyc: KycNamespace;
+    readonly recovery: RecoveryNamespace;
+    readonly session: SessionNamespace;
+    readonly settings: SettingsNamespace;
+    readonly yieldOps: YieldNamespace;
+    /** Raw context, for advanced use cases (custom telemetry, manual refresh). */
+    readonly _internal: AcceslyContextValue;
+}
+declare function useAccesly(): AcceslyHook;
+
+/**
+ * `useWalletStatus()` — status on-chain del Smart Account del user actual con
+ * push real-time vía SSE.
+ *
+ * Reemplaza el polling cada 30s del legacy. Comportamiento:
+ *
+ *   1. SSE-first: si `walletStreamUrl` está configurado y `EventSource` existe,
+ *      se suscribe al canal `status` del `wallet-stream` Lambda. Cero polling.
+ *   2. Fallback a polling backoff (1s → 30s) si SSE no está disponible.
+ *   3. Pausa cuando `document.hidden`, retoma al volver.
+ *   4. `refresh()` fuerza fetch HTTP inmediato.
+ *
+ * El status del Smart Account vive en DDB (lo que el backend reporta de su
+ * verificación contra Soroban). El backend push-ea cambios cuando los detecta
+ * (cada 5s en el loop del wallet-stream).
+ */
+type WalletStatusValue = 'on-chain' | 'pending-deploy' | 'unknown' | 'no-wallet';
+interface UseWalletStatusResult {
+    readonly status: WalletStatusValue;
+    readonly walletAddress: string | null;
+    readonly onChain: boolean | null;
+    readonly isStale: boolean;
+    refresh(): Promise<void>;
+}
+declare function useWalletStatus(): UseWalletStatusResult;
+
+/**
+ * `useBalance(walletAddress?)` — devuelve el balance XLM del Smart Account
+ * con push real-time vía SSE.
+ *
+ * Si SSE está configurado (env tiene `walletStreamUrl` y `EventSource` existe),
+ * el hook se suscribe al canal `balance` del `wallet-stream` Lambda y se
+ * actualiza instantáneamente cuando cambia el balance on-chain.
+ *
+ * Fallback automático a polling cada 10s si SSE no está disponible (entorno
+ * que no lo soporta o backend self-hosteado sin el endpoint).
+ *
+ * El `walletAddress` se auto-resuelve desde el `DeviceStore` si no se pasa
+ * (cubrir el caso "wallet del user actual sin tener que pasarla a mano").
+ */
+interface UseBalanceResult {
+    /** Stroops como string base-10. `null` mientras se carga o no hay address. */
+    readonly stroops: string | null;
+    /** Mismo balance como string decimal en XLM. `null` mientras se carga. */
+    readonly xlm: string | null;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    /** Fuerza fetch HTTP inmediato (útil tras una operación del user). */
+    refresh(): Promise<void>;
+}
+declare function useBalance(walletAddress?: string | null): UseBalanceResult;
+
+/**
+ * `WalletSubscription` — singleton manager por wallet address que abre UNA
+ * sola conexión `EventSource` al `wallet-stream` Lambda y desmultiplexa los
+ * eventos a múltiples subscribers (hooks).
+ *
+ * Beneficios:
+ *  - 3 hooks (`useBalance`, `useWalletActivity`, `useWalletStatus`) sobre la
+ *    misma wallet → 1 sola conexión TCP, no 3 polls separados.
+ *  - Auto-reconnect cuando el server cierra (default de EventSource — `retry:`).
+ *  - Ref-count: la conexión se abre con el primer subscriber y se cierra
+ *    cuando no quedan listeners (`useEffect` cleanup en cada hook).
+ *  - Eventos cacheados: el último valor recibido de cada tipo se replay-ea
+ *    a nuevos subscribers para que no esperen el próximo push.
+ *
+ * Sin SSE configurado (`walletStreamUrl` vacío) o cuando `EventSource` no
+ * existe (SSR / workers), los hooks individuales detectan el flag
+ * `unavailable` y caen al polling fallback que ya existe.
+ */
+type WalletStreamEventType = 'status' | 'balance' | 'activity';
+interface WalletStreamStatusPayload {
+    readonly walletAddress: string | null;
+    readonly onChain: boolean | null;
+}
+interface WalletStreamBalancePayload {
+    readonly stroops: string;
+    readonly xlm: string;
+}
+/**
+ * Activity emitida por el backend ya **filtrada y tipada** — solo eventos
+ * relevantes para una wallet de Accesly (rotación de signers + transfers
+ * IN/OUT de XLM). Otros eventos on-chain (debug, errores host, eventos
+ * irrelevantes) se descartan en el server.
+ */
+type WalletActivityItem = {
+    readonly type: 'signer-rotated';
+    readonly txHash: string;
+    readonly ledger: number;
+    readonly timestamp: string | null;
+    readonly newOwnerEd25519Hex: string;
+} | {
+    readonly type: 'transfer-in';
+    readonly txHash: string;
+    readonly ledger: number;
+    readonly timestamp: string | null;
+    readonly from: string;
+    readonly amountStroops: string;
+} | {
+    readonly type: 'transfer-out';
+    readonly txHash: string;
+    readonly ledger: number;
+    readonly timestamp: string | null;
+    readonly to: string;
+    readonly amountStroops: string;
+};
+interface WalletStreamActivityPayload {
+    readonly events: readonly WalletActivityItem[];
+}
+type Listener<T> = (payload: T) => void;
+/**
+ * Suscribirse a un tipo de evento de la wallet. Devuelve una función
+ * de cleanup que el caller (típicamente `useEffect`) debe llamar para
+ * desuscribir y, eventualmente, cerrar la conexión SSE.
+ *
+ * Si SSE no está disponible (URL vacía, EventSource undefined), devuelve
+ * `null` para indicar al caller que use el fallback de polling.
+ */
+declare function subscribeToWalletEvent<T extends WalletStreamEventType>(streamUrl: string, walletAddress: string, eventType: T, listener: T extends 'status' ? Listener<WalletStreamStatusPayload> : T extends 'balance' ? Listener<WalletStreamBalancePayload> : Listener<WalletStreamActivityPayload>): (() => void) | null;
+/**
+ * Cierra TODAS las conexiones SSE activas. Útil para tests o cuando el user
+ * cierra sesión y querés limpiar conexiones colgadas. Llamar en `auth.signOut`
+ * lo tienen pendiente como mejora — por ahora el cleanup natural de los
+ * unmount basta.
+ */
+declare function closeAllWalletSubscriptions(): void;
+
+/**
+ * `useWalletActivity(walletAddress?, opts?)` — actividad on-chain relevante de
+ * la wallet (rotate_signer + transfers in/out de XLM) con push real-time vía SSE.
+ *
+ * El backend YA filtra eventos irrelevantes — el integrador solo recibe
+ * `WalletActivityItem` tipados (`signer-rotated` | `transfer-in` | `transfer-out`).
+ * Sin parsing manual de XDR ni lógica de filtrado client-side.
+ *
+ * Fallback: si SSE no está disponible, polling cada 25s al endpoint
+ * `/wallets/:address/activity`. Mucho menos eficiente pero garantiza data.
+ */
+
+interface UseWalletActivityOptions {
+    /** Cantidad de eventos a mostrar (cap del buffer del cliente). Default 20. */
+    readonly limit?: number;
+}
+interface UseWalletActivityResult {
+    /** Eventos tipados, más recientes primero. */
+    readonly events: readonly WalletActivityItem[];
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    refresh(): Promise<void>;
+}
+declare function useWalletActivity(walletAddress?: string | null, opts?: UseWalletActivityOptions): UseWalletActivityResult;
+
+/**
+ * @accesly/react — React Provider + `useAccesly` hook.
+ *
+ * Wraps `@accesly/core` for React 18+. Apps integrate with:
+ *
+ *   import { AcceslyProvider, useAccesly } from '@accesly/react';
+ *
+ *   function App() {
+ *     return (
+ *       <AcceslyProvider appId="my-app" env="dev">
+ *         <YourApp />
+ *       </AcceslyProvider>
+ *     );
+ *   }
+ *
+ *   function Login() {
+ *     const { auth } = useAccesly();
+ *     return (
+ *       <button onClick={() => auth.signIn(email, password)}>Sign in</button>
+ *     );
+ *   }
+ */
+declare const REACT_ADAPTER_VERSION = "0.0.0";
+
+export { AcceslyContext, type AcceslyContextValue, type AcceslyHook, AcceslyProvider, type AcceslyProviderProps, type AuthNamespace, type BootstrapWalletInput, type CreateWalletInput, type CreatedWalletInfo, ENVIRONMENT_DEFAULTS, type EnsureWalletResult, type EnvironmentDefaults, type FinalizeRecoveryInput, type FinalizeRecoveryResult, type KycNamespace, NotImplementedYetError, REACT_ADAPTER_VERSION, type ReconstructedSeed, type RecoveryNamespace, type RemoteWalletInfo, type RetryDeployResult, type SendXlmInput, type SendXlmResult, type SessionNamespace, type SettingsNamespace, type TxNamespace, type UnlockedSigningMaterial, type UseBalanceResult, type UseWalletActivityOptions, type UseWalletActivityResult, type UseWalletStatusResult, type WalletActivityItem, type WalletNamespace, type WalletStatus, type WalletStatusValue, type WalletStreamActivityPayload, type WalletStreamBalancePayload, type WalletStreamEventType, type WalletStreamStatusPayload, type YieldNamespace, closeAllWalletSubscriptions, subscribeToWalletEvent, useAccesly, useBalance, useWalletActivity, useWalletStatus };