@massalabs/gossip-sdk 0.0.2-dev.20260128094509

package/src/utils.ts

@@ -0,0 +1,47 @@
+/**
+ * SDK Utilities
+ *
+ * Helper functions for SDK configuration.
+ *
+ * @example
+ * ```typescript
+ * import { configureSdk } from 'gossip-sdk';
+ *
+ * configureSdk({
+ *   db,
+ *   protocolBaseUrl: 'https://api.example.com',
+ * });
+ * ```
+ */
+
+import type { GossipDatabase } from './db';
+import { setDb } from './db';
+import { startWasmInitialization } from './wasm/loader';
+import { setProtocolBaseUrl } from './config/protocol';
+
+export interface SdkRuntimeConfig {
+  db?: GossipDatabase;
+  protocolBaseUrl?: string;
+}
+
+/**
+ * Configure runtime adapters for the SDK.
+ * Call this once during application startup.
+ *
+ * This also starts WASM initialization in the background.
+ *
+ * Note: Service instances (MessageService, AnnouncementService, etc.)
+ * should be created by the app with the required dependencies.
+ */
+export function configureSdk(config: SdkRuntimeConfig): void {
+  if (config.db) {
+    setDb(config.db);
+  }
+
+  if (config.protocolBaseUrl) {
+    setProtocolBaseUrl(config.protocolBaseUrl);
+  }
+
+  // Start WASM initialization in the background (non-blocking)
+  startWasmInitialization();
+}

package/src/wasm/encryption.ts

@@ -0,0 +1,108 @@
+/**
+ * Encryption, Keys, and AEAD Support
+ *
+ * This file provides proxy functions for EncryptionKey, Nonce classes,
+ * and AEAD (Authenticated Encryption with Additional Data) operations,
+ * ensuring proper initialization before calling any WASM functions.
+ */
+
+import { ensureWasmInitialized } from './loader';
+import {
+  EncryptionKey,
+  Nonce,
+  aead_encrypt as _aead_encrypt,
+  aead_decrypt as _aead_decrypt,
+} from '../assets/generated/wasm/gossip_wasm';
+
+// Re-export classes
+export { EncryptionKey, Nonce };
+
+/**
+ * Generate a new random encryption key (64 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export async function generateEncryptionKey(): Promise<EncryptionKey> {
+  await ensureWasmInitialized();
+  return EncryptionKey.generate();
+}
+
+/**
+ * Generate a deterministic encryption key (64 bytes) from a seed string.
+ * This ensures WASM is initialized before calling.
+ */
+export async function generateEncryptionKeyFromSeed(
+  seed: string,
+  salt: Uint8Array
+): Promise<EncryptionKey> {
+  await ensureWasmInitialized();
+  return EncryptionKey.from_seed(seed, salt);
+}
+
+/**
+ * Create an encryption key from raw bytes (must be 64 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export async function encryptionKeyFromBytes(
+  bytes: Uint8Array
+): Promise<EncryptionKey> {
+  await ensureWasmInitialized();
+  return EncryptionKey.from_bytes(bytes);
+}
+
+/**
+ * Generate a new random nonce (16 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export async function generateNonce(): Promise<Nonce> {
+  await ensureWasmInitialized();
+  return Nonce.generate();
+}
+
+/**
+ * Create a nonce from raw bytes (must be 16 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export async function nonceFromBytes(bytes: Uint8Array): Promise<Nonce> {
+  await ensureWasmInitialized();
+  return Nonce.from_bytes(bytes);
+}
+
+/**
+ * Encrypt data using AES-256-SIV authenticated encryption
+ * This ensures WASM is initialized before calling
+ *
+ * @param key - The encryption key (64 bytes)
+ * @param nonce - The nonce (16 bytes, should be unique per encryption)
+ * @param plaintext - The data to encrypt
+ * @param aad - Additional authenticated data (not encrypted, but authenticated)
+ * @returns The ciphertext with authentication tag appended
+ */
+export async function encryptAead(
+  key: EncryptionKey,
+  nonce: Nonce,
+  plaintext: Uint8Array,
+  aad: Uint8Array
+): Promise<Uint8Array> {
+  await ensureWasmInitialized();
+  return _aead_encrypt(key, nonce, plaintext, aad);
+}
+
+/**
+ * Decrypt data using AES-256-SIV authenticated encryption
+ * This ensures WASM is initialized before calling
+ *
+ * @param key - The encryption key (64 bytes, must match encryption key)
+ * @param nonce - The nonce (16 bytes, must match encryption nonce)
+ * @param ciphertext - The encrypted data with authentication tag
+ * @param aad - Additional authenticated data (must match encryption AAD)
+ * @returns The decrypted plaintext, or undefined if authentication fails
+ */
+export async function decryptAead(
+  key: EncryptionKey,
+  nonce: Nonce,
+  ciphertext: Uint8Array,
+  aad: Uint8Array
+): Promise<Uint8Array | undefined> {
+  await ensureWasmInitialized();
+  return _aead_decrypt(key, nonce, ciphertext, aad);
+}

package/src/wasm/index.ts

@@ -0,0 +1,20 @@
+/**
+ * WASM Module Exports
+ *
+ * This file provides a clean interface for importing WASM modules
+ * and related functionality.
+ */
+
+// Export modules
+export { SessionModule, sessionStatusToString } from './session';
+
+// Export initialization functions
+export {
+  initializeWasm,
+  ensureWasmInitialized,
+  startWasmInitialization,
+} from './loader';
+
+// Export specialized WASM functionality
+export * from './encryption';
+export * from './userKeys';

package/src/wasm/loader.ts

@@ -0,0 +1,123 @@
+/**
+ * WASM Module Loader and Initialization Service
+ *
+ * This file handles both WASM core initialization and module loading.
+ * It ensures WASM modules are initialized once and properly throughout
+ * the application lifecycle.
+ */
+
+import init from '../assets/generated/wasm/gossip_wasm';
+
+/**
+ * Check if we're running in Node.js environment
+ */
+function isNodeEnvironment(): boolean {
+  return (
+    typeof process !== 'undefined' &&
+    process.versions != null &&
+    process.versions.node != null
+  );
+}
+
+/**
+ * Load WASM module for Node.js environment using fs.readFileSync
+ */
+async function loadWasmForNode(): Promise<WebAssembly.Module> {
+  // Dynamic import to avoid bundling Node.js modules in browser builds
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+
+  // Get the directory of the current module
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  // Resolve path to WASM file - WASM is in the SDK's generated folder
+  const wasmPath = path.resolve(
+    __dirname,
+    '../assets/generated/wasm/gossip_wasm_bg.wasm'
+  );
+
+  // Read WASM file as binary
+  const wasmBuffer = fs.readFileSync(wasmPath);
+
+  // Instantiate WASM module
+  const wasmModule = await WebAssembly.compile(wasmBuffer);
+  return wasmModule;
+}
+
+/**
+ * WASM Initialization State
+ */
+let isInitializing = false;
+let isInitialized = false;
+let initializationPromise: Promise<void> | null = null;
+let initError: Error | null = null;
+
+/**
+ * Initialize WASM modules if not already initialized
+ * This function is idempotent - safe to call multiple times
+ */
+export async function initializeWasm(): Promise<void> {
+  // If already initialized, return immediately
+  if (isInitialized) {
+    return;
+  }
+
+  // If initialization is in progress, wait for it to complete
+  if (isInitializing && initializationPromise) {
+    return initializationPromise;
+  }
+
+  // Start initialization
+  isInitializing = true;
+  initError = null;
+
+  initializationPromise = (async () => {
+    try {
+      // In Node.js environment, load WASM using fs.readFileSync
+      if (isNodeEnvironment()) {
+        const wasmModule = await loadWasmForNode();
+        await init(wasmModule);
+      } else {
+        // In browser/jsdom, use default init (which uses fetch)
+        await init();
+      }
+      isInitialized = true;
+      isInitializing = false;
+    } catch (error) {
+      initError = error as Error;
+      isInitializing = false;
+      console.error('[WASM] Failed to initialize WASM modules:', error);
+      throw error;
+    }
+  })();
+
+  return initializationPromise;
+}
+
+/**
+ * Ensure WASM is initialized, throwing an error if initialization failed
+ */
+export async function ensureWasmInitialized(): Promise<void> {
+  await initializeWasm();
+
+  if (initError) {
+    throw new Error(`WASM initialization failed: ${initError.message}`);
+  }
+
+  if (!isInitialized) {
+    throw new Error('WASM not initialized');
+  }
+}
+
+/**
+ * Start WASM initialization in the background.
+ * Call this early in the app lifecycle (for example in main.tsx).
+ */
+export function startWasmInitialization(): void {
+  // Fire and forget - start initialization in background
+  initializeWasm().catch(error => {
+    console.error('[WASM] Background initialization error:', error);
+  });
+}

package/src/wasm/session.ts

@@ -0,0 +1,276 @@
+/**
+ * Session Module Implementation
+ *
+ * This file contains the real WASM implementation of the SessionModule
+ * using SessionManagerWrapper and related WASM classes.
+ */
+
+import {
+  SessionManagerWrapper,
+  UserPublicKeys,
+  UserSecretKeys,
+  ReceiveMessageOutput,
+  SendMessageOutput,
+  SessionStatus,
+  EncryptionKey,
+  SessionConfig,
+  AnnouncementResult,
+  UserKeys,
+} from '../assets/generated/wasm/gossip_wasm';
+import { UserProfile } from '../db';
+import { encodeUserId } from '../utils/userId';
+
+export class SessionModule {
+  private sessionManager: SessionManagerWrapper | null = null;
+  private onPersist?: () => Promise<void>; // Async callback for persistence
+  public ourPk: UserPublicKeys;
+  public ourSk: UserSecretKeys;
+  public userId: Uint8Array;
+  public userIdEncoded: string;
+
+  constructor(
+    userKeys: UserKeys,
+    onPersist?: () => Promise<void>,
+    config?: SessionConfig
+  ) {
+    this.ourPk = userKeys.public_keys();
+    this.ourSk = userKeys.secret_keys();
+    this.userId = this.ourPk.derive_id();
+    this.userIdEncoded = encodeUserId(this.userId);
+
+    const sessionConfig = config ?? SessionConfig.new_default();
+    this.sessionManager = new SessionManagerWrapper(sessionConfig);
+    this.onPersist = onPersist;
+  }
+
+  /**
+   * Set the persistence callback
+   */
+  setOnPersist(callback: () => Promise<void>): void {
+    this.onPersist = callback;
+  }
+
+  /**
+   * Helper to trigger persistence after state changes.
+   * Returns a promise that resolves when persistence is complete.
+   * IMPORTANT: Callers should await this before sending data to network
+   * to prevent state loss on app crash.
+   */
+  private async persistIfNeeded(): Promise<void> {
+    if (this.onPersist) {
+      await this.onPersist();
+    }
+  }
+
+  /**
+   * Trigger persistence explicitly and wait for completion.
+   * Use this when you need to ensure state is saved before proceeding.
+   */
+  async persist(): Promise<void> {
+    await this.persistIfNeeded();
+  }
+
+  /**
+   * Initialize session from an encrypted blob
+   */
+  load(profile: UserProfile, encryptionKey: EncryptionKey): void {
+    // Clean up existing session if any
+    this.cleanup();
+
+    this.sessionManager = SessionManagerWrapper.from_encrypted_blob(
+      profile.session,
+      encryptionKey
+    );
+  }
+
+  /**
+   * Serialize session to an encrypted blob
+   */
+  toEncryptedBlob(key: EncryptionKey): Uint8Array {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    return this.sessionManager.to_encrypted_blob(key);
+  }
+
+  cleanup(): void {
+    this.sessionManager?.free();
+    this.sessionManager = null;
+  }
+
+  /**
+   * Establish an outgoing session with a peer via the underlying WASM wrapper
+   * @param peerPk - The peer's public keys
+   * @param userData - Optional user data to include in the announcement (defaults to empty array)
+   * @returns The announcement bytes to publish
+   */
+  async establishOutgoingSession(
+    peerPk: UserPublicKeys,
+    userData?: Uint8Array
+  ): Promise<Uint8Array> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    const userDataBytes = userData ?? new Uint8Array(0);
+    const result = this.sessionManager.establish_outgoing_session(
+      peerPk,
+      this.ourPk,
+      this.ourSk,
+      userDataBytes
+    );
+
+    if (result.length === 0) {
+      throw new Error(
+        'Failed to establish outgoing session. Session manager returned empty announcement bytes.'
+      );
+    }
+
+    await this.persistIfNeeded();
+    return result;
+  }
+
+  /**
+   * Feed an incoming announcement into the session manager
+   * @returns AnnouncementResult containing the announcer's public keys, timestamp, and user data, or undefined if invalid
+   */
+  async feedIncomingAnnouncement(
+    announcementBytes: Uint8Array
+  ): Promise<AnnouncementResult | undefined> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    const result = this.sessionManager.feed_incoming_announcement(
+      announcementBytes,
+      this.ourPk,
+      this.ourSk
+    );
+
+    if (result) {
+      await this.persistIfNeeded();
+    }
+    return result;
+  }
+
+  /**
+   * Get the list of message board read keys (seekers) to monitor
+   */
+  getMessageBoardReadKeys(): Array<Uint8Array> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    return this.sessionManager.get_message_board_read_keys();
+  }
+
+  /**
+   * Process an incoming ciphertext from the message board
+   */
+  async feedIncomingMessageBoardRead(
+    seeker: Uint8Array,
+    ciphertext: Uint8Array
+  ): Promise<ReceiveMessageOutput | undefined> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    const result = this.sessionManager.feed_incoming_message_board_read(
+      seeker,
+      ciphertext,
+      this.ourSk
+    );
+
+    await this.persistIfNeeded();
+    return result;
+  }
+
+  /**
+   * Send a message to a peer.
+   * IMPORTANT: This persists session state before returning.
+   * The returned output should only be sent to network AFTER this resolves.
+   */
+  async sendMessage(
+    peerId: Uint8Array,
+    message: Uint8Array
+  ): Promise<SendMessageOutput | undefined> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    const result = this.sessionManager.send_message(peerId, message);
+    // CRITICAL: Persist session state BEFORE returning
+    // This ensures state is saved before the encrypted message goes on the network
+    await this.persistIfNeeded();
+    return result;
+  }
+
+  /**
+   * List all known peer IDs
+   */
+  peerList(): Array<Uint8Array> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    return this.sessionManager.peer_list();
+  }
+
+  /**
+   * Get the session status for a peer
+   */
+  peerSessionStatus(peerId: Uint8Array): SessionStatus {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    return this.sessionManager.peer_session_status(peerId);
+  }
+
+  /**
+   * Discard a peer and all associated session state
+   */
+  async peerDiscard(peerId: Uint8Array): Promise<void> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    this.sessionManager.peer_discard(peerId);
+    await this.persistIfNeeded();
+  }
+
+  /**
+   * Refresh sessions, returning peer IDs that need keep-alive messages
+   */
+  async refresh(): Promise<Array<Uint8Array>> {
+    if (!this.sessionManager) {
+      throw new Error('Session manager is not initialized');
+    }
+
+    const result = this.sessionManager.refresh();
+    await this.persistIfNeeded();
+    return result;
+  }
+}
+
+export function sessionStatusToString(status: SessionStatus): string {
+  switch (status) {
+    case SessionStatus.Active:
+      return 'Active';
+    case SessionStatus.UnknownPeer:
+      return 'UnknownPeer';
+    case SessionStatus.NoSession:
+      return 'NoSession';
+    case SessionStatus.PeerRequested:
+      return 'PeerRequested';
+    case SessionStatus.SelfRequested:
+      return 'SelfRequested';
+    case SessionStatus.Killed:
+      return 'Killed';
+    case SessionStatus.Saturated:
+      return 'Saturated';
+    default:
+      throw new Error(`Unknown session status: ${status}`);
+  }
+}

package/src/wasm/userKeys.ts

@@ -0,0 +1,31 @@
+/**
+ * User Keys Support
+ *
+ * This file provides proxy functions for user key generation,
+ * ensuring proper initialization before calling any WASM functions.
+ */
+
+import { ensureWasmInitialized } from './loader';
+import {
+  generate_user_keys as _generate_user_keys,
+  UserKeys,
+} from '../assets/generated/wasm/gossip_wasm';
+
+// Re-export classes
+export { UserKeys };
+
+/**
+ * Generate user keys from a passphrase using password-based key derivation
+ * This ensures WASM is initialized before calling
+ *
+ * @param passphrase - The user's passphrase
+ * @param secondaryKey - A 32-byte secondary public key
+ * @returns UserKeys object containing public and secret keys
+ */
+export async function generateUserKeys(passphrase: string): Promise<UserKeys> {
+  await ensureWasmInitialized();
+  // The actual WASM function is synchronous, so we can call it directly
+  const keys = _generate_user_keys(passphrase);
+
+  return keys;
+}

package/test/config/protocol.spec.ts

@@ -0,0 +1,31 @@
+/**
+ * Protocol config tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  protocolConfig,
+  setProtocolBaseUrl,
+  resetProtocolBaseUrl,
+} from '../../src/config/protocol';
+
+describe('protocol config', () => {
+  beforeEach(() => {
+    resetProtocolBaseUrl();
+  });
+
+  afterEach(() => {
+    resetProtocolBaseUrl();
+  });
+
+  it('uses runtime override when provided', () => {
+    setProtocolBaseUrl('https://custom.example.com/api');
+    expect(protocolConfig.baseUrl).toBe('https://custom.example.com/api');
+  });
+
+  it('resets to default after override', () => {
+    setProtocolBaseUrl('https://custom.example.com/api');
+    resetProtocolBaseUrl();
+    expect(protocolConfig.baseUrl).toBe('https://api.usegossip.com/api');
+  });
+});