@accesly/react 1.1.2 → 1.1.3

package/dist/index.d.cts

@@ -0,0 +1,778 @@
+import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord, EncryptedEnvelope, WalletActivityEvent } 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;
+    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()` — hook event-driven que sustituye al
+ * `setInterval(fetchRemote, 30_000)` que cada integrador escribía en su
+ * `Wallet.tsx` / `CreateWallet.tsx`.
+ *
+ * Comportamiento:
+ *
+ *   1. **SSE-first.** Si la infra del backend expone `GET /wallets/stream`
+ *      (Lambda function URL con response streaming), el hook se suscribe vía
+ *      `EventSource` y reacciona instantáneamente a cambios on-chain. Cero
+ *      polling, cero latencia.
+ *
+ *   2. **Polling con backoff inteligente como fallback.** Si SSE no está
+ *      disponible (backend viejo, sandbox sin streaming, browser sin
+ *      `EventSource`), cae a polling con backoff exponencial:
+ *        - mientras la wallet NO está `'on-chain'`: 2s → 5s → 10s → 20s →
+ *          30s (cap).
+ *        - si llega `'on-chain'` o el tab queda oculto: polling pausado.
+ *        - llamadas de `refresh()` resetean el backoff a 2s.
+ *      Mucho mejor UX que el `30s` constante del legacy.
+ *
+ *   3. **`document.visibilityState` aware.** Pausa cuando el tab está oculto;
+ *      retoma + refresca inmediatamente cuando vuelve a visible.
+ *
+ *   4. **Cross-tab via `BroadcastChannel`.** Si el user tiene la app abierta
+ *      en 2 tabs, el primero que reciba un update lo emite por el canal
+ *      `accesly:wallet:<username>` y los otros tabs lo aplican sin hacer su
+ *      propio fetch — un solo round-trip por update.
+ *
+ * Devuelve `{ status, walletAddress, onChain, isStale, refresh }`. `refresh()`
+ * fuerza un fetch inmediato + resetea backoff. `isStale` = `true` si no se ha
+ * podido confirmar status en > 60s (red/Soroban RPC caído).
+ */
+type WalletStatusValue = 'on-chain' | 'pending-deploy' | 'unknown' | 'no-wallet';
+interface UseWalletStatusResult {
+    /** Status actual. `'no-wallet'` si el backend nunca recibió un POST /wallets. */
+    readonly status: WalletStatusValue;
+    /** Address C…, o null si no hay wallet. */
+    readonly walletAddress: string | null;
+    /** Mirror del campo `onChain` del backend (true / false / null). */
+    readonly onChain: boolean | null;
+    /** True si el último fetch exitoso fue hace más de 60s — UI puede mostrar warning. */
+    readonly isStale: boolean;
+    /** Fuerza fetch inmediato + resetea backoff. Llamalo tras submit/recovery. */
+    refresh(): Promise<void>;
+}
+declare function useWalletStatus(): UseWalletStatusResult;
+
+/**
+ * `useBalance(walletAddress?)` — hook que devuelve el balance XLM del Smart
+ * Account con auto-refresh.
+ *
+ * Si no se le pasa `walletAddress`, intenta auto-resolverlo via
+ * `wallet.getStoredCredential(username)` del DeviceStore — el flujo más
+ * común (un solo wallet por user en este device).
+ *
+ * Polling: 8s mientras tab visible, pausa cuando hidden, retoma al volver.
+ * También se refresca inmediatamente cuando `useWalletStatus` reporta
+ * `'on-chain'` (via cross-tab `BroadcastChannel`) para mostrar el balance
+ * tras un deploy fresco.
+ */
+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;
+    /** True durante el primer fetch (subsiguientes ediciones son silent). */
+    readonly isLoading: boolean;
+    /** Error del último fetch, si lo hubo. */
+    readonly error: Error | null;
+    /** Fuerza fetch inmediato. */
+    refresh(): Promise<void>;
+}
+declare function useBalance(walletAddress?: string | null): UseBalanceResult;
+
+/**
+ * `useWalletActivity(walletAddress?, opts?)` — hook que devuelve los últimos
+ * eventos on-chain del Smart Account, auto-refrescados cada 20s mientras la
+ * tab está visible.
+ *
+ * Pasos:
+ *   1. Resuelve `walletAddress` desde el DeviceStore si no se pasa explícito.
+ *   2. Fetch inicial inmediato → guarda en estado.
+ *   3. Polling cada 20s (pausado si tab oculta).
+ *   4. `refresh()` para fetch on-demand tras una operación del user.
+ *
+ * Mejor UX que el "ver explorer link" porque la app puede renderizar la
+ * lista de tx en su propio look — sin abrir otro tab a Stellar Expert.
+ */
+
+interface UseWalletActivityOptions {
+    /** Cantidad de eventos a pedir. Default 20, max 50. */
+    readonly limit?: number;
+}
+interface UseWalletActivityResult {
+    readonly events: readonly WalletActivityEvent[];
+    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 WalletNamespace, type WalletStatus, type WalletStatusValue, type YieldNamespace, useAccesly, useBalance, useWalletActivity, useWalletStatus };