@the9ines/bolt-core 0.5.2 → 0.6.0

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/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,4 +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,5 +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;

package/dist/wasm-crypto.js

@@ -0,0 +1,119 @@
+/**
+ * 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).
+ */
+/** WASM adapter instance. null until initWasmCrypto() succeeds. */
+let _wasmCrypto = null;
+/** Whether WASM init has been attempted. */
+let _initAttempted = false;
+/**
+ * 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 function getWasmCrypto() {
+    return _wasmCrypto;
+}
+/**
+ * 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)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function initWasmCryptoFromModule(wasmModule) {
+    if (_wasmCrypto)
+        return true;
+    try {
+        _wasmModule = wasmModule;
+        _wasmCrypto = {
+            generateEphemeralKeyPair: () => wasmModule.generateEphemeralKeyPair(),
+            generateIdentityKeyPair: () => wasmModule.generateIdentityKeyPair(),
+            sealBoxPayload: (p, rpk, sk) => wasmModule.sealBoxPayload(p, rpk, sk),
+            openBoxPayload: (s, spk, rsk) => wasmModule.openBoxPayload(s, spk, rsk),
+            computeSas: (ia, ib, ea, eb) => wasmModule.computeSas(ia, ib, ea, eb),
+            generateSecurePeerCode: () => wasmModule.generateSecurePeerCode(),
+            isValidPeerCode: (c) => wasmModule.isValidPeerCode(c),
+            sha256Hex: (d) => wasmModule.sha256Hex(d),
+        };
+        console.log('[BOLT-WASM] Protocol authority initialized (Rust/WASM: crypto + BTR + transfer)');
+        return true;
+    }
+    catch (e) {
+        console.warn('[BOLT-WASM] Failed to initialize from module:', e);
+        _wasmCrypto = null;
+        _wasmModule = null;
+        return false;
+    }
+}
+/**
+ * Initialize WASM crypto. Legacy entry point — attempts dynamic import.
+ * Prefer initProtocolWasm() from @the9ines/bolt-transport-web instead.
+ */
+export async function initWasmCrypto() {
+    if (_initAttempted)
+        return _wasmCrypto !== null;
+    _initAttempted = true;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const wasm = await (Function('return import("bolt-protocol-wasm")')());
+        await wasm.default();
+        return initWasmCryptoFromModule(wasm);
+    }
+    catch (e) {
+        console.warn('[BOLT-WASM] Failed to initialize — falling back to TS protocol:', e);
+        _wasmCrypto = null;
+        return false;
+    }
+}
+// ══════════════════════════════════════════════════════════════════
+// RB4: BTR + Transfer State Authority
+// ══════════════════════════════════════════════════════════════════
+/** WASM module reference for constructing opaque handles. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _wasmModule = null;
+/**
+ * Get the raw WASM module for constructing BTR/transfer handles.
+ * Returns null if WASM not initialized.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getWasmModule() {
+    return _wasmModule;
+}
+/**
+ * Create a WASM-backed BTR engine. Returns null if WASM not available.
+ * Caller must call .free() when done to zeroize key material.
+ */
+export function createWasmBtrEngine(sharedSecret) {
+    if (!_wasmModule)
+        return null;
+    try {
+        return new _wasmModule.WasmBtrEngine(sharedSecret);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create a WASM-backed send session. Returns null if WASM not available.
+ * Rust owns transfer-state transitions. TS proposes events; Rust validates.
+ */
+export function createWasmSendSession() {
+    if (!_wasmModule)
+        return null;
+    try {
+        return new _wasmModule.WasmSendSession();
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the9ines/bolt-core",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Bolt Protocol core crypto primitives and utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,8 +15,8 @@
     "build": "tsc",
     "test": "vitest run",
     "audit-exports": "node scripts/audit-exports.mjs",
-    "generate-vectors": "node scripts/print-test-vectors.mjs",
-    "check-vectors": "node scripts/print-test-vectors.mjs --check",
+    "generate-vectors": "echo '[DEPRECATED] Use: cargo test -p bolt-core --features vectors --test vector_golden_core' && node scripts/print-test-vectors.mjs",
+    "check-vectors": "echo '[DEPRECATED] Canonical vectors are now Rust-generated. Use: cargo test -p bolt-core --features vectors' && node scripts/print-test-vectors.mjs --check",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {