@massalabs/gossip-sdk 0.0.2-dev.20260128094509 → 0.0.2-dev.20260128111120

package/dist/utils/validation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Validation Utilities
+ *
+ * Functions for validating user input like usernames, passwords, and user IDs.
+ */
+import { type GossipDatabase } from '../db';
+export type ValidationResult = {
+    valid: true;
+    error?: never;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validate a password meets requirements
+ *
+ * @param value - The password to validate
+ * @returns Validation result
+ */
+export declare function validatePassword(value: string): ValidationResult;
+/**
+ * Validate a username format (without checking availability)
+ *
+ * @param value - The username to validate
+ * @returns Validation result
+ */
+export declare function validateUsernameFormat(value: string): ValidationResult;
+/**
+ * Validate a username is available (not already in use)
+ *
+ * @param value - The username to check
+ * @param db - Database instance
+ * @returns Validation result
+ */
+export declare function validateUsernameAvailability(value: string, db: GossipDatabase): Promise<ValidationResult>;
+/**
+ * Validate a username format and availability
+ *
+ * @param value - The username to validate
+ * @param db - Database instance
+ * @returns Validation result
+ */
+export declare function validateUsernameFormatAndAvailability(value: string, db: GossipDatabase): Promise<ValidationResult>;
+/**
+ * Validate a user ID format (Bech32 gossip1... format)
+ *
+ * @param value - The user ID to validate
+ * @returns Validation result
+ */
+export declare function validateUserIdFormat(value: string): ValidationResult;

package/dist/utils/validation.js

@@ -0,0 +1,112 @@
+/**
+ * Validation Utilities
+ *
+ * Functions for validating user input like usernames, passwords, and user IDs.
+ */
+import { isValidUserId } from './userId';
+/**
+ * Validate a password meets requirements
+ *
+ * @param value - The password to validate
+ * @returns Validation result
+ */
+export function validatePassword(value) {
+    if (!value || value.trim().length === 0) {
+        return { valid: false, error: 'Password is required' };
+    }
+    if (value.length < 8) {
+        return {
+            valid: false,
+            error: 'Password must be at least 8 characters long',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate a username format (without checking availability)
+ *
+ * @param value - The username to validate
+ * @returns Validation result
+ */
+export function validateUsernameFormat(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return { valid: false, error: 'Username is required' };
+    }
+    // Disallow any whitespace inside the username (single token only)
+    if (/\s/.test(trimmed)) {
+        return {
+            valid: false,
+            error: 'Username cannot contain spaces',
+        };
+    }
+    if (trimmed.length < 3) {
+        return {
+            valid: false,
+            error: 'Username must be at least 3 characters long',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate a username is available (not already in use)
+ *
+ * @param value - The username to check
+ * @param db - Database instance
+ * @returns Validation result
+ */
+export async function validateUsernameAvailability(value, db) {
+    try {
+        if (!db.isOpen()) {
+            await db.open();
+        }
+        const existingProfile = await db.userProfile
+            .filter((profile) => profile.username.trim().toLowerCase() === value.trim().toLowerCase())
+            .first();
+        if (existingProfile) {
+            return {
+                valid: false,
+                error: 'This username is already in use. Please choose another.',
+            };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error
+                ? error.message
+                : 'Unable to verify username availability. Please try again.',
+        };
+    }
+}
+/**
+ * Validate a username format and availability
+ *
+ * @param value - The username to validate
+ * @param db - Database instance
+ * @returns Validation result
+ */
+export async function validateUsernameFormatAndAvailability(value, db) {
+    const result = validateUsernameFormat(value);
+    if (!result.valid) {
+        return result;
+    }
+    return await validateUsernameAvailability(value, db);
+}
+/**
+ * Validate a user ID format (Bech32 gossip1... format)
+ *
+ * @param value - The user ID to validate
+ * @returns Validation result
+ */
+export function validateUserIdFormat(value) {
+    const userId = value.trim();
+    if (!isValidUserId(userId)) {
+        return {
+            valid: false,
+            error: 'Invalid format — must be a valid user ID',
+        };
+    }
+    return { valid: true };
+}

package/dist/utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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';
+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 declare function configureSdk(config: SdkRuntimeConfig): void;

package/{src/utils.ts → dist/utils.js}

@@ -13,17 +13,9 @@
  * });
  * ```
  */
-
-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.
@@ -33,15 +25,13 @@ export interface SdkRuntimeConfig {
  * 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();
+export function configureSdk(config) {
+    if (config.db) {
+        setDb(config.db);
+    }
+    if (config.protocolBaseUrl) {
+        setProtocolBaseUrl(config.protocolBaseUrl);
+    }
+    // Start WASM initialization in the background (non-blocking)
+    startWasmInitialization();
 }

package/dist/wasm/encryption.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { EncryptionKey, Nonce } from '../assets/generated/wasm/gossip_wasm';
+export { EncryptionKey, Nonce };
+/**
+ * Generate a new random encryption key (64 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export declare function generateEncryptionKey(): Promise<EncryptionKey>;
+/**
+ * Generate a deterministic encryption key (64 bytes) from a seed string.
+ * This ensures WASM is initialized before calling.
+ */
+export declare function generateEncryptionKeyFromSeed(seed: string, salt: Uint8Array): Promise<EncryptionKey>;
+/**
+ * Create an encryption key from raw bytes (must be 64 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export declare function encryptionKeyFromBytes(bytes: Uint8Array): Promise<EncryptionKey>;
+/**
+ * Generate a new random nonce (16 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export declare function generateNonce(): Promise<Nonce>;
+/**
+ * Create a nonce from raw bytes (must be 16 bytes)
+ * This ensures WASM is initialized before calling
+ */
+export declare function nonceFromBytes(bytes: Uint8Array): Promise<Nonce>;
+/**
+ * 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 declare function encryptAead(key: EncryptionKey, nonce: Nonce, plaintext: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
+/**
+ * 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 declare function decryptAead(key: EncryptionKey, nonce: Nonce, ciphertext: Uint8Array, aad: Uint8Array): Promise<Uint8Array | undefined>;

package/{src/wasm/encryption.ts → dist/wasm/encryption.js}

@@ -5,68 +5,50 @@
  * 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';
-
+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();
+export async function generateEncryptionKey() {
+    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);
+export async function generateEncryptionKeyFromSeed(seed, salt) {
+    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);
+export async function encryptionKeyFromBytes(bytes) {
+    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();
+export async function generateNonce() {
+    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);
+export async function nonceFromBytes(bytes) {
+    await ensureWasmInitialized();
+    return Nonce.from_bytes(bytes);
 }
-
 /**
  * Encrypt data using AES-256-SIV authenticated encryption
  * This ensures WASM is initialized before calling
@@ -77,16 +59,10 @@ export async function nonceFromBytes(bytes: Uint8Array): Promise<Nonce> {
  * @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);
+export async function encryptAead(key, nonce, plaintext, aad) {
+    await ensureWasmInitialized();
+    return _aead_encrypt(key, nonce, plaintext, aad);
 }
-
 /**
  * Decrypt data using AES-256-SIV authenticated encryption
  * This ensures WASM is initialized before calling
@@ -97,12 +73,7 @@ export async function encryptAead(
  * @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);
+export async function decryptAead(key, nonce, ciphertext, aad) {
+    await ensureWasmInitialized();
+    return _aead_decrypt(key, nonce, ciphertext, aad);
 }

package/dist/wasm/index.d.ts

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

package/{src/wasm/index.ts → dist/wasm/index.js}

@@ -4,17 +4,10 @@
  * 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 { initializeWasm, ensureWasmInitialized, startWasmInitialization, } from './loader';
 // Export specialized WASM functionality
 export * from './encryption';
 export * from './userKeys';

package/dist/wasm/loader.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+/**
+ * Initialize WASM modules if not already initialized
+ * This function is idempotent - safe to call multiple times
+ */
+export declare function initializeWasm(): Promise<void>;
+/**
+ * Ensure WASM is initialized, throwing an error if initialization failed
+ */
+export declare function ensureWasmInitialized(): Promise<void>;
+/**
+ * Start WASM initialization in the background.
+ * Call this early in the app lifecycle (for example in main.tsx).
+ */
+export declare function startWasmInitialization(): void;

package/dist/wasm/loader.js

@@ -0,0 +1,103 @@
+/**
+ * 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() {
+    return (typeof process !== 'undefined' &&
+        process.versions != null &&
+        process.versions.node != null);
+}
+/**
+ * Load WASM module for Node.js environment using fs.readFileSync
+ */
+async function loadWasmForNode() {
+    // 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 = null;
+let initError = null;
+/**
+ * Initialize WASM modules if not already initialized
+ * This function is idempotent - safe to call multiple times
+ */
+export async function initializeWasm() {
+    // 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;
+            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() {
+    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() {
+    // Fire and forget - start initialization in background
+    initializeWasm().catch(error => {
+        console.error('[WASM] Background initialization error:', error);
+    });
+}

package/dist/wasm/session.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Session Module Implementation
+ *
+ * This file contains the real WASM implementation of the SessionModule
+ * using SessionManagerWrapper and related WASM classes.
+ */
+import { UserPublicKeys, UserSecretKeys, ReceiveMessageOutput, SendMessageOutput, SessionStatus, EncryptionKey, SessionConfig, AnnouncementResult, UserKeys } from '../assets/generated/wasm/gossip_wasm';
+import { UserProfile } from '../db';
+export declare class SessionModule {
+    private sessionManager;
+    private onPersist?;
+    ourPk: UserPublicKeys;
+    ourSk: UserSecretKeys;
+    userId: Uint8Array;
+    userIdEncoded: string;
+    constructor(userKeys: UserKeys, onPersist?: () => Promise<void>, config?: SessionConfig);
+    /**
+     * Set the persistence callback
+     */
+    setOnPersist(callback: () => Promise<void>): void;
+    /**
+     * 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 persistIfNeeded;
+    /**
+     * Trigger persistence explicitly and wait for completion.
+     * Use this when you need to ensure state is saved before proceeding.
+     */
+    persist(): Promise<void>;
+    /**
+     * Initialize session from an encrypted blob
+     */
+    load(profile: UserProfile, encryptionKey: EncryptionKey): void;
+    /**
+     * Serialize session to an encrypted blob
+     */
+    toEncryptedBlob(key: EncryptionKey): Uint8Array;
+    cleanup(): void;
+    /**
+     * 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
+     */
+    establishOutgoingSession(peerPk: UserPublicKeys, userData?: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Feed an incoming announcement into the session manager
+     * @returns AnnouncementResult containing the announcer's public keys, timestamp, and user data, or undefined if invalid
+     */
+    feedIncomingAnnouncement(announcementBytes: Uint8Array): Promise<AnnouncementResult | undefined>;
+    /**
+     * Get the list of message board read keys (seekers) to monitor
+     */
+    getMessageBoardReadKeys(): Array<Uint8Array>;
+    /**
+     * Process an incoming ciphertext from the message board
+     */
+    feedIncomingMessageBoardRead(seeker: Uint8Array, ciphertext: Uint8Array): Promise<ReceiveMessageOutput | undefined>;
+    /**
+     * 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.
+     */
+    sendMessage(peerId: Uint8Array, message: Uint8Array): Promise<SendMessageOutput | undefined>;
+    /**
+     * List all known peer IDs
+     */
+    peerList(): Array<Uint8Array>;
+    /**
+     * Get the session status for a peer
+     */
+    peerSessionStatus(peerId: Uint8Array): SessionStatus;
+    /**
+     * Discard a peer and all associated session state
+     */
+    peerDiscard(peerId: Uint8Array): Promise<void>;
+    /**
+     * Refresh sessions, returning peer IDs that need keep-alive messages
+     */
+    refresh(): Promise<Array<Uint8Array>>;
+}
+export declare function sessionStatusToString(status: SessionStatus): string;