@the9ines/bolt-core 0.5.1 → 0.6.0

package/dist/btr/state.d.ts

@@ -0,0 +1,81 @@
+/**
+ * BTR session/transfer/chain state — §16.5 key material lifecycle.
+ *
+ * BtrEngine: session-level ratchet state.
+ * BtrTransferContext: per-transfer chain state for seal/open.
+ *
+ * Must match Rust bolt-btr/src/state.rs semantics exactly.
+ */
+/**
+ * BTR engine — manages session-level ratchet state.
+ *
+ * Owns the session_root_key, ratchet generation counter, and replay guard.
+ * Create via `new BtrEngine(ephemeralSharedSecret)` after handshake completes.
+ */
+export declare class BtrEngine {
+    private sessionRootKey;
+    private _ratchetGeneration;
+    private replayGuard;
+    constructor(ephemeralSharedSecret: Uint8Array);
+    /** Current ratchet generation (monotonically increasing per session). */
+    get ratchetGeneration(): number;
+    /** Current session root key (for testing/vector generation only). */
+    getSessionRootKey(): Uint8Array;
+    /**
+     * Prepare to send a FILE_OFFER — generate local ratchet keypair and
+     * perform DH ratchet step with remote peer's ratchet public key.
+     *
+     * Returns [BtrTransferContext, localRatchetPublicKey].
+     */
+    beginTransferSend(transferId: Uint8Array, remoteRatchetPub: Uint8Array): [BtrTransferContext, Uint8Array];
+    /**
+     * Accept a transfer — perform DH ratchet step with the sender's
+     * ratchet public key from their FILE_OFFER envelope.
+     *
+     * Returns [BtrTransferContext, localRatchetPublicKey].
+     */
+    beginTransferReceive(transferId: Uint8Array, remoteRatchetPub: Uint8Array): [BtrTransferContext, Uint8Array];
+    /** Check a received chunk's replay/ordering status. */
+    checkReplay(transferId: Uint8Array, generation: number, chainIndex: number): void;
+    /** End the current transfer's replay tracking. */
+    endTransfer(): void;
+    /** Cleanup on disconnect — zero ALL BTR state. */
+    cleanupDisconnect(): void;
+}
+/**
+ * BTR transfer context — manages per-transfer chain state.
+ *
+ * Created by BtrEngine.beginTransferSend/Receive.
+ * Used for encrypting/decrypting chunks within a single transfer.
+ */
+export declare class BtrTransferContext {
+    private _transferId;
+    private _generation;
+    private _chainKey;
+    private _chainIndex;
+    constructor(transferId: Uint8Array, generation: number, chainKey: Uint8Array);
+    get transferId(): Uint8Array;
+    get generation(): number;
+    get chainIndex(): number;
+    /** Current chain key (for testing only). */
+    getChainKey(): Uint8Array;
+    /**
+     * Encrypt a chunk at the current chain position.
+     *
+     * Advances the chain: derives message_key and next_chain_key,
+     * encrypts plaintext via NaCl secretbox.
+     *
+     * Returns [chainIndex, sealedBytes].
+     */
+    sealChunk(plaintext: Uint8Array): [number, Uint8Array];
+    /**
+     * Decrypt a chunk at the expected chain position.
+     *
+     * Same chain advance as sealChunk — both peers derive identical keys.
+     */
+    openChunk(expectedChainIndex: number, sealed: Uint8Array): Uint8Array;
+    /** Cleanup on transfer complete (FILE_FINISH). */
+    cleanupComplete(): void;
+    /** Cleanup on transfer cancel (CANCEL). */
+    cleanupCancel(): void;
+}

package/dist/btr/state.js

@@ -0,0 +1,146 @@
+/**
+ * BTR session/transfer/chain state — §16.5 key material lifecycle.
+ *
+ * BtrEngine: session-level ratchet state.
+ * BtrTransferContext: per-transfer chain state for seal/open.
+ *
+ * Must match Rust bolt-btr/src/state.rs semantics exactly.
+ */
+import { deriveSessionRoot, deriveTransferRoot, chainAdvance } from './key-schedule.js';
+import { deriveRatchetedSessionRoot, generateRatchetKeypair, scalarMult } from './ratchet.js';
+import { btrSeal, btrOpen } from './encrypt.js';
+import { ratchetChainError } from './errors.js';
+import { ReplayGuard } from './replay.js';
+/**
+ * BTR engine — manages session-level ratchet state.
+ *
+ * Owns the session_root_key, ratchet generation counter, and replay guard.
+ * Create via `new BtrEngine(ephemeralSharedSecret)` after handshake completes.
+ */
+export class BtrEngine {
+    constructor(ephemeralSharedSecret) {
+        this.sessionRootKey = deriveSessionRoot(ephemeralSharedSecret);
+        this._ratchetGeneration = 0;
+        this.replayGuard = new ReplayGuard();
+    }
+    /** Current ratchet generation (monotonically increasing per session). */
+    get ratchetGeneration() {
+        return this._ratchetGeneration;
+    }
+    /** Current session root key (for testing/vector generation only). */
+    getSessionRootKey() {
+        return this.sessionRootKey;
+    }
+    /**
+     * Prepare to send a FILE_OFFER — generate local ratchet keypair and
+     * perform DH ratchet step with remote peer's ratchet public key.
+     *
+     * Returns [BtrTransferContext, localRatchetPublicKey].
+     */
+    beginTransferSend(transferId, remoteRatchetPub) {
+        const localKp = generateRatchetKeypair();
+        const localPub = localKp.publicKey;
+        // DH ratchet step
+        const dhOutput = scalarMult(localKp.secretKey, remoteRatchetPub);
+        const newSrk = deriveRatchetedSessionRoot(this.sessionRootKey, dhOutput);
+        // Update session state
+        this.sessionRootKey = newSrk;
+        this._ratchetGeneration += 1;
+        // Derive transfer root
+        const transferRoot = deriveTransferRoot(this.sessionRootKey, transferId);
+        // Set up replay guard for this transfer
+        this.replayGuard.beginTransfer(transferId, this._ratchetGeneration);
+        const ctx = new BtrTransferContext(new Uint8Array(transferId), this._ratchetGeneration, transferRoot);
+        return [ctx, localPub];
+    }
+    /**
+     * Accept a transfer — perform DH ratchet step with the sender's
+     * ratchet public key from their FILE_OFFER envelope.
+     *
+     * Returns [BtrTransferContext, localRatchetPublicKey].
+     */
+    beginTransferReceive(transferId, remoteRatchetPub) {
+        return this.beginTransferSend(transferId, remoteRatchetPub);
+    }
+    /** Check a received chunk's replay/ordering status. */
+    checkReplay(transferId, generation, chainIndex) {
+        this.replayGuard.check(transferId, generation, chainIndex);
+    }
+    /** End the current transfer's replay tracking. */
+    endTransfer() {
+        this.replayGuard.endTransfer();
+    }
+    /** Cleanup on disconnect — zero ALL BTR state. */
+    cleanupDisconnect() {
+        this.sessionRootKey.fill(0);
+        this._ratchetGeneration = 0;
+        this.replayGuard.reset();
+    }
+}
+/**
+ * BTR transfer context — manages per-transfer chain state.
+ *
+ * Created by BtrEngine.beginTransferSend/Receive.
+ * Used for encrypting/decrypting chunks within a single transfer.
+ */
+export class BtrTransferContext {
+    constructor(transferId, generation, chainKey) {
+        this._transferId = transferId;
+        this._generation = generation;
+        this._chainKey = chainKey;
+        this._chainIndex = 0;
+    }
+    get transferId() {
+        return this._transferId;
+    }
+    get generation() {
+        return this._generation;
+    }
+    get chainIndex() {
+        return this._chainIndex;
+    }
+    /** Current chain key (for testing only). */
+    getChainKey() {
+        return this._chainKey;
+    }
+    /**
+     * Encrypt a chunk at the current chain position.
+     *
+     * Advances the chain: derives message_key and next_chain_key,
+     * encrypts plaintext via NaCl secretbox.
+     *
+     * Returns [chainIndex, sealedBytes].
+     */
+    sealChunk(plaintext) {
+        const idx = this._chainIndex;
+        const { messageKey, nextChainKey } = chainAdvance(this._chainKey);
+        const sealed = btrSeal(messageKey, plaintext);
+        this._chainKey = nextChainKey;
+        this._chainIndex += 1;
+        return [idx, sealed];
+    }
+    /**
+     * Decrypt a chunk at the expected chain position.
+     *
+     * Same chain advance as sealChunk — both peers derive identical keys.
+     */
+    openChunk(expectedChainIndex, sealed) {
+        if (expectedChainIndex !== this._chainIndex) {
+            throw ratchetChainError(`chain_index mismatch: expected ${this._chainIndex}, got ${expectedChainIndex}`);
+        }
+        const { messageKey, nextChainKey } = chainAdvance(this._chainKey);
+        const plaintext = btrOpen(messageKey, sealed);
+        this._chainKey = nextChainKey;
+        this._chainIndex += 1;
+        return plaintext;
+    }
+    /** Cleanup on transfer complete (FILE_FINISH). */
+    cleanupComplete() {
+        this._chainKey.fill(0);
+        this._transferId.fill(0);
+    }
+    /** Cleanup on transfer cancel (CANCEL). */
+    cleanupCancel() {
+        this.cleanupComplete();
+    }
+}

package/dist/crypto.d.ts

@@ -1,6 +1,8 @@
 /**
  * Generate a fresh ephemeral X25519 keypair for a single connection.
  * Discard after session ends.
+ *
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export declare function generateEphemeralKeyPair(): {
     publicKey: Uint8Array;
@@ -10,12 +12,8 @@ export declare function generateEphemeralKeyPair(): {
  * Seal a plaintext payload using NaCl box (XSalsa20-Poly1305).
  *
  * Wire format: base64(nonce || ciphertext)
- * This matches the exact format used by all current product repos.
  *
- * @param plaintext - Raw bytes to encrypt
- * @param remotePublicKey - Receiver's ephemeral public key (32 bytes)
- * @param senderSecretKey - Sender's ephemeral secret key (32 bytes)
- * @returns base64-encoded string of nonce + ciphertext
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export declare function sealBoxPayload(plaintext: Uint8Array, remotePublicKey: Uint8Array, senderSecretKey: Uint8Array): string;
 /**
@@ -23,9 +21,6 @@ export declare function sealBoxPayload(plaintext: Uint8Array, remotePublicKey: U
  *
  * Expects wire format: base64(nonce || ciphertext)
  *
- * @param sealed - base64-encoded string from sealBoxPayload
- * @param senderPublicKey - Sender's ephemeral public key (32 bytes)
- * @param receiverSecretKey - Receiver's ephemeral secret key (32 bytes)
- * @returns Decrypted plaintext bytes
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export declare function openBoxPayload(sealed: string, senderPublicKey: Uint8Array, receiverSecretKey: Uint8Array): Uint8Array;

package/dist/crypto.js

@@ -2,25 +2,30 @@ import tweetnacl from 'tweetnacl';
 const { box, randomBytes } = tweetnacl;
 import { toBase64, fromBase64 } from './encoding.js';
 import { EncryptionError } from './errors.js';
+import { getWasmCrypto } from './wasm-crypto.js';
 /**
  * Generate a fresh ephemeral X25519 keypair for a single connection.
  * Discard after session ends.
+ *
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export function generateEphemeralKeyPair() {
+    const wasm = getWasmCrypto();
+    if (wasm)
+        return wasm.generateEphemeralKeyPair();
     return box.keyPair();
 }
 /**
  * Seal a plaintext payload using NaCl box (XSalsa20-Poly1305).
  *
  * Wire format: base64(nonce || ciphertext)
- * This matches the exact format used by all current product repos.
  *
- * @param plaintext - Raw bytes to encrypt
- * @param remotePublicKey - Receiver's ephemeral public key (32 bytes)
- * @param senderSecretKey - Sender's ephemeral secret key (32 bytes)
- * @returns base64-encoded string of nonce + ciphertext
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export function sealBoxPayload(plaintext, remotePublicKey, senderSecretKey) {
+    const wasm = getWasmCrypto();
+    if (wasm)
+        return wasm.sealBoxPayload(plaintext, remotePublicKey, senderSecretKey);
     const nonce = randomBytes(box.nonceLength);
     const encrypted = box(plaintext, nonce, remotePublicKey, senderSecretKey);
     if (!encrypted)
@@ -35,12 +40,12 @@ export function sealBoxPayload(plaintext, remotePublicKey, senderSecretKey) {
  *
  * Expects wire format: base64(nonce || ciphertext)
  *
- * @param sealed - base64-encoded string from sealBoxPayload
- * @param senderPublicKey - Sender's ephemeral public key (32 bytes)
- * @param receiverSecretKey - Receiver's ephemeral secret key (32 bytes)
- * @returns Decrypted plaintext bytes
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export function openBoxPayload(sealed, senderPublicKey, receiverSecretKey) {
+    const wasm = getWasmCrypto();
+    if (wasm)
+        return wasm.openBoxPayload(sealed, senderPublicKey, receiverSecretKey);
     const data = fromBase64(sealed);
     if (data.length < box.nonceLength) {
         throw new EncryptionError('Sealed payload too short');

package/dist/errors.d.ts

@@ -15,11 +15,11 @@ export declare class IntegrityError extends BoltError {
     constructor(message?: string);
 }
 /**
- * Canonical wire error code registry — 22 codes (11 PROTOCOL + 11 ENFORCEMENT).
+ * Canonical wire error code registry — 26 codes (11 PROTOCOL + 11 ENFORCEMENT + 4 BTR).
  * Every error frame sent on the wire MUST use a code from this array.
  * Implementations MUST reject inbound error frames carrying codes not listed here.
  */
-export declare const WIRE_ERROR_CODES: readonly ["VERSION_MISMATCH", "ENCRYPTION_FAILED", "INTEGRITY_FAILED", "REPLAY_DETECTED", "TRANSFER_FAILED", "LIMIT_EXCEEDED", "CONNECTION_LOST", "PEER_NOT_FOUND", "ALREADY_CONNECTED", "INVALID_STATE", "KEY_MISMATCH", "DUPLICATE_HELLO", "ENVELOPE_REQUIRED", "ENVELOPE_UNNEGOTIATED", "ENVELOPE_DECRYPT_FAIL", "ENVELOPE_INVALID", "HELLO_PARSE_ERROR", "HELLO_DECRYPT_FAIL", "HELLO_SCHEMA_ERROR", "INVALID_MESSAGE", "UNKNOWN_MESSAGE_TYPE", "PROTOCOL_VIOLATION"];
+export declare const WIRE_ERROR_CODES: readonly ["VERSION_MISMATCH", "ENCRYPTION_FAILED", "INTEGRITY_FAILED", "REPLAY_DETECTED", "TRANSFER_FAILED", "LIMIT_EXCEEDED", "CONNECTION_LOST", "PEER_NOT_FOUND", "ALREADY_CONNECTED", "INVALID_STATE", "KEY_MISMATCH", "DUPLICATE_HELLO", "ENVELOPE_REQUIRED", "ENVELOPE_UNNEGOTIATED", "ENVELOPE_DECRYPT_FAIL", "ENVELOPE_INVALID", "HELLO_PARSE_ERROR", "HELLO_DECRYPT_FAIL", "HELLO_SCHEMA_ERROR", "INVALID_MESSAGE", "UNKNOWN_MESSAGE_TYPE", "PROTOCOL_VIOLATION", "RATCHET_STATE_ERROR", "RATCHET_CHAIN_ERROR", "RATCHET_DECRYPT_FAIL", "RATCHET_DOWNGRADE_REJECTED"];
 /** A valid wire error code string from PROTOCOL.md §10. */
 export type WireErrorCode = (typeof WIRE_ERROR_CODES)[number];
 /** Type guard: returns true if `x` is a canonical wire error code. */

package/dist/errors.js

@@ -31,7 +31,7 @@ export class IntegrityError extends BoltError {
 }
 // ── Wire Error Code Registry (PROTOCOL.md §10, v0.1.3-spec) ──────────
 /**
- * Canonical wire error code registry — 22 codes (11 PROTOCOL + 11 ENFORCEMENT).
+ * Canonical wire error code registry — 26 codes (11 PROTOCOL + 11 ENFORCEMENT + 4 BTR).
  * Every error frame sent on the wire MUST use a code from this array.
  * Implementations MUST reject inbound error frames carrying codes not listed here.
  */
@@ -60,6 +60,11 @@ export const WIRE_ERROR_CODES = [
     'INVALID_MESSAGE',
     'UNKNOWN_MESSAGE_TYPE',
     'PROTOCOL_VIOLATION',
+    // BTR class (4) — §16.7
+    'RATCHET_STATE_ERROR',
+    'RATCHET_CHAIN_ERROR',
+    'RATCHET_DECRYPT_FAIL',
+    'RATCHET_DOWNGRADE_REJECTED',
 ];
 /** Type guard: returns true if `x` is a canonical wire error code. */
 export function isValidWireErrorCode(x) {

package/dist/identity.d.ts

@@ -7,9 +7,7 @@ export interface IdentityKeyPair {
 /**
  * Generate a persistent identity keypair (X25519).
  *
- * Identity keys are long-lived and stored by the transport layer.
- * They MUST NOT be sent through the signaling server — identity
- * material travels only inside encrypted DataChannel messages (HELLO).
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export declare function generateIdentityKeyPair(): IdentityKeyPair;
 /**

package/dist/identity.js

@@ -1,14 +1,16 @@
 import tweetnacl from 'tweetnacl';
 const { box } = tweetnacl;
 import { BoltError } from './errors.js';
+import { getWasmCrypto } from './wasm-crypto.js';
 /**
  * Generate a persistent identity keypair (X25519).
  *
- * Identity keys are long-lived and stored by the transport layer.
- * They MUST NOT be sent through the signaling server — identity
- * material travels only inside encrypted DataChannel messages (HELLO).
+ * RB3: Uses Rust/WASM when available, falls back to tweetnacl.
  */
 export function generateIdentityKeyPair() {
+    const wasm = getWasmCrypto();
+    if (wasm)
+        return wasm.generateIdentityKeyPair();
     return box.keyPair();
 }
 /**

package/dist/index.d.ts

@@ -9,3 +9,6 @@ export type { IdentityKeyPair } from './identity.js';
 export { BoltError, EncryptionError, ConnectionError, TransferError, IntegrityError } from './errors.js';
 export { WIRE_ERROR_CODES, isValidWireErrorCode } from './errors.js';
 export type { WireErrorCode } from './errors.js';
+export { initWasmCrypto, initWasmCryptoFromModule, getWasmCrypto, getWasmModule, createWasmBtrEngine, createWasmSendSession } from './wasm-crypto.js';
+export type { WasmCryptoAdapter, WasmBtrEngineHandle, WasmBtrTransferCtxHandle, WasmSendSessionHandle } from './wasm-crypto.js';
+export * from './btr/index.js';

package/dist/index.js

@@ -16,3 +16,7 @@ export { generateIdentityKeyPair, KeyMismatchError } from './identity.js';
 export { BoltError, EncryptionError, ConnectionError, TransferError, IntegrityError } from './errors.js';
 // Wire error code registry (PROTOCOL.md §10)
 export { WIRE_ERROR_CODES, isValidWireErrorCode } from './errors.js';
+// WASM protocol adapter (RUSTIFY-BROWSER-CORE-1 RB3+RB4)
+export { initWasmCrypto, initWasmCryptoFromModule, getWasmCrypto, getWasmModule, createWasmBtrEngine, createWasmSendSession } from './wasm-crypto.js';
+// Bolt Transfer Ratchet (BTR) — §16
+export * from './btr/index.js';

package/dist/sas.d.ts

@@ -10,4 +10,10 @@
  * @param ephemeralB - Raw 32-byte ephemeral public key of peer B
  * @returns 6-character uppercase hex string (24 bits of entropy)
  */
+/**
+ * Compute a 6-character SAS (Short Authentication String) per PROTOCOL.md.
+ *
+ * RB3: Uses Rust/WASM (sync) when available, falls back to TS Web Crypto (async).
+ * Return type remains Promise<string> for backward compatibility.
+ */
 export declare function computeSas(identityA: Uint8Array, identityB: Uint8Array, ephemeralA: Uint8Array, ephemeralB: Uint8Array): Promise<string>;

package/dist/sas.js

@@ -1,5 +1,6 @@
 import { sha256, bufferToHex } from './hash.js';
 import { PUBLIC_KEY_LENGTH, SAS_LENGTH } from './constants.js';
+import { getWasmCrypto } from './wasm-crypto.js';
 // CANONICAL: computeSas() is the ONLY SAS implementation in the Bolt ecosystem.
 // SAS verification is not yet surfaced in products. No SAS logic may exist in
 // transport or product packages. See scripts/verify-no-shadow-sas.sh.
@@ -35,7 +36,19 @@ function sort32(a, b) {
  * @param ephemeralB - Raw 32-byte ephemeral public key of peer B
  * @returns 6-character uppercase hex string (24 bits of entropy)
  */
+/**
+ * Compute a 6-character SAS (Short Authentication String) per PROTOCOL.md.
+ *
+ * RB3: Uses Rust/WASM (sync) when available, falls back to TS Web Crypto (async).
+ * Return type remains Promise<string> for backward compatibility.
+ */
 export async function computeSas(identityA, identityB, ephemeralA, ephemeralB) {
+    // RB3: WASM path (sync — Rust SHA-256, no Web Crypto)
+    const wasm = getWasmCrypto();
+    if (wasm) {
+        return wasm.computeSas(identityA, identityB, ephemeralA, ephemeralB);
+    }
+    // TS fallback (async — Web Crypto digest)
     if (identityA.length !== PUBLIC_KEY_LENGTH || identityB.length !== PUBLIC_KEY_LENGTH) {
         throw new Error(`Identity keys must be ${PUBLIC_KEY_LENGTH} bytes`);
     }

package/dist/wasm-crypto.d.ts

@@ -0,0 +1,118 @@
+/**
+ * WASM-backed protocol adapter (RUSTIFY-BROWSER-CORE-1 RB3+RB4).
+ *
+ * RB3: crypto/session/SAS functions backed by Rust/WASM.
+ * RB4: BTR state (BtrEngine, BtrTransferCtx) + transfer state (SendSession)
+ *      backed by Rust/WASM opaque handles.
+ *
+ * TS tweetnacl/BTR implementations remain as fallback (PM-RB-03: condition-gated).
+ */
+export interface WasmCryptoAdapter {
+    generateEphemeralKeyPair(): {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+    generateIdentityKeyPair(): {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+    sealBoxPayload(plaintext: Uint8Array, remotePublicKey: Uint8Array, senderSecretKey: Uint8Array): string;
+    openBoxPayload(sealed: string, senderPublicKey: Uint8Array, receiverSecretKey: Uint8Array): Uint8Array;
+    computeSas(identityA: Uint8Array, identityB: Uint8Array, ephemeralA: Uint8Array, ephemeralB: Uint8Array): string;
+    generateSecurePeerCode(): string;
+    isValidPeerCode(code: string): boolean;
+    sha256Hex(data: Uint8Array): string;
+}
+/**
+ * Get the WASM crypto adapter, or null if not initialized or init failed.
+ * Callers should fall back to TS crypto if this returns null.
+ */
+export declare function getWasmCrypto(): WasmCryptoAdapter | null;
+/**
+ * Initialize WASM crypto from a pre-loaded WASM module.
+ *
+ * BR2: Accepts an already-loaded+initialized WASM module (provided by
+ * transport-web's initProtocolWasm()). This avoids bare module specifier
+ * issues — the loader lives in transport-web where the artifact is embedded.
+ *
+ * PM-RB-03: TS fallback remains operational if this is never called.
+ *
+ * @param wasmModule - The loaded bolt-protocol-wasm module (with exported functions)
+ */
+export declare function initWasmCryptoFromModule(wasmModule: any): boolean;
+/**
+ * Initialize WASM crypto. Legacy entry point — attempts dynamic import.
+ * Prefer initProtocolWasm() from @the9ines/bolt-transport-web instead.
+ */
+export declare function initWasmCrypto(): Promise<boolean>;
+/**
+ * Get the raw WASM module for constructing BTR/transfer handles.
+ * Returns null if WASM not initialized.
+ */
+export declare function getWasmModule(): any;
+/**
+ * Opaque BTR engine handle. Rust owns all key material.
+ * Wraps WasmBtrEngine from bolt-protocol-wasm.
+ *
+ * Usage:
+ *   const engine = createWasmBtrEngine(sharedSecret);
+ *   const ctx = engine.beginTransferSend(transferId, remoteRatchetPub);
+ *   const { chainIndex, sealed } = ctx.sealChunk(plaintext);
+ *   engine.free();  // zeroize when done
+ */
+export interface WasmBtrEngineHandle {
+    beginTransferSend(transferId: Uint8Array, remoteRatchetPub: Uint8Array): WasmBtrTransferCtxHandle;
+    beginTransferReceive(transferId: Uint8Array, remoteRatchetPub: Uint8Array): WasmBtrTransferCtxHandle;
+    ratchetGeneration(): number;
+    endTransfer(): void;
+    cleanupDisconnect(): void;
+    free(): void;
+}
+export interface WasmBtrTransferCtxHandle {
+    sealChunk(plaintext: Uint8Array): {
+        chainIndex: number;
+        sealed: Uint8Array;
+    };
+    openChunk(expectedIndex: number, sealed: Uint8Array): Uint8Array;
+    chainIndex(): number;
+    generation(): number;
+    transferId(): Uint8Array;
+    localRatchetPub(): Uint8Array;
+    cleanupComplete(): void;
+    cleanupCancel(): void;
+    free(): void;
+}
+export interface WasmSendSessionHandle {
+    beginSend(transferId: string, payload: Uint8Array, filename: string, fileHash?: string): {
+        transferId: string;
+        filename: string;
+        size: number;
+        totalChunks: number;
+        chunkSize: number;
+        fileHash?: string;
+    };
+    onAccept(transferId: string): void;
+    onCancel(transferId: string): void;
+    onPause(transferId: string): void;
+    onResume(transferId: string): void;
+    nextChunk(): {
+        transferId: string;
+        chunkIndex: number;
+        totalChunks: number;
+        data: Uint8Array;
+    } | null;
+    finish(): string;
+    state(): string;
+    isSendActive(): boolean;
+    free(): void;
+}
+/**
+ * Create a WASM-backed BTR engine. Returns null if WASM not available.
+ * Caller must call .free() when done to zeroize key material.
+ */
+export declare function createWasmBtrEngine(sharedSecret: Uint8Array): WasmBtrEngineHandle | null;
+/**
+ * Create a WASM-backed send session. Returns null if WASM not available.
+ * Rust owns transfer-state transitions. TS proposes events; Rust validates.
+ */
+export declare function createWasmSendSession(): WasmSendSessionHandle | null;