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

package/dist/api/messageProtocol/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Message Protocol Module
+ *
+ * Factory functions and exports for message protocol implementations.
+ */
+export type { EncryptedMessage, IMessageProtocol, MessageProtocolResponse, BulletinItem, } from './types';
+export { RestMessageProtocol } from './rest';
+export { MessageProtocol } from './mock';
+import type { IMessageProtocol } from './types';
+import { type MessageProtocolType } from '../../config/protocol';
+/**
+ * Factory function to create message protocol instances
+ */
+export declare function createMessageProtocol(type?: MessageProtocolType, config?: Partial<{
+    baseUrl: string;
+    timeout: number;
+    retryAttempts: number;
+}>): IMessageProtocol;
+export declare const restMessageProtocol: IMessageProtocol;

package/dist/api/messageProtocol/index.js

@@ -0,0 +1,26 @@
+/**
+ * Message Protocol Module
+ *
+ * Factory functions and exports for message protocol implementations.
+ */
+export { RestMessageProtocol } from './rest';
+export { MessageProtocol } from './mock';
+import { defaultMessageProtocol, protocolConfig, } from '../../config/protocol';
+import { RestMessageProtocol } from './rest';
+import { MessageProtocol } from './mock';
+/**
+ * Factory function to create message protocol instances
+ */
+export function createMessageProtocol(type = defaultMessageProtocol, config) {
+    switch (type) {
+        case 'rest': {
+            return new RestMessageProtocol(config?.baseUrl || protocolConfig.baseUrl, config?.timeout || 10000, config?.retryAttempts || 3);
+        }
+        case 'mock': {
+            return new MessageProtocol(config?.baseUrl || protocolConfig.baseUrl, config?.timeout || 10000, config?.retryAttempts || 3);
+        }
+        default:
+            throw new Error(`Unsupported message protocol type: ${type}`);
+    }
+}
+export const restMessageProtocol = createMessageProtocol();

package/dist/api/messageProtocol/mock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message Protocol Implementation
+ *
+ * Provides a concrete protocol class backed by the REST implementation.
+ * This uses the real Gossip API rather than a mock transport.
+ */
+import { RestMessageProtocol } from './rest';
+/**
+ * Create a MessageProtocol instance backed by REST.
+ */
+export declare class MessageProtocol extends RestMessageProtocol {
+}

package/{src/api/messageProtocol/mock.ts → dist/api/messageProtocol/mock.js}

@@ -4,10 +4,9 @@
  * Provides a concrete protocol class backed by the REST implementation.
  * This uses the real Gossip API rather than a mock transport.
  */
-
 import { RestMessageProtocol } from './rest';
-
 /**
  * Create a MessageProtocol instance backed by REST.
  */
-export class MessageProtocol extends RestMessageProtocol {}
+export class MessageProtocol extends RestMessageProtocol {
+}

package/dist/api/messageProtocol/rest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * REST API implementation of the message protocol
+ */
+import { BulletinItem, EncryptedMessage, IMessageProtocol, MessageProtocolResponse } from './types';
+export type BulletinsPage = {
+    counter: string;
+    data: string;
+}[];
+export declare class RestMessageProtocol implements IMessageProtocol {
+    private baseUrl;
+    private timeout;
+    private retryAttempts;
+    constructor(baseUrl: string, timeout?: number, retryAttempts?: number);
+    fetchMessages(seekers: Uint8Array[]): Promise<EncryptedMessage[]>;
+    sendMessage(message: EncryptedMessage): Promise<void>;
+    sendAnnouncement(announcement: Uint8Array): Promise<string>;
+    fetchAnnouncements(limit?: number, cursor?: string): Promise<BulletinItem[]>;
+    fetchPublicKeyByUserId(userId: Uint8Array): Promise<string>;
+    postPublicKey(base64PublicKeys: string): Promise<string>;
+    private makeRequest;
+    changeNode(nodeUrl?: string): Promise<MessageProtocolResponse>;
+}

package/dist/api/messageProtocol/rest.js

@@ -0,0 +1,161 @@
+/**
+ * REST API implementation of the message protocol
+ */
+import { encodeToBase64, decodeFromBase64 } from '../../utils/base64';
+const BULLETIN_ENDPOINT = '/bulletin';
+const MESSAGES_ENDPOINT = '/messages';
+export class RestMessageProtocol {
+    constructor(baseUrl, timeout = 10000, retryAttempts = 3) {
+        Object.defineProperty(this, "baseUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: baseUrl
+        });
+        Object.defineProperty(this, "timeout", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: timeout
+        });
+        Object.defineProperty(this, "retryAttempts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: retryAttempts
+        });
+    }
+    // TODO: Implement a fetch with pagination to avoid fetching all messages at once
+    async fetchMessages(seekers) {
+        const url = `${this.baseUrl}${MESSAGES_ENDPOINT}/fetch`;
+        const response = await this.makeRequest(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ seekers: seekers.map(encodeToBase64) }),
+        });
+        if (!response.success || !response.data) {
+            throw new Error(response.error || 'Failed to fetch messages');
+        }
+        return response.data.map((item) => {
+            const seeker = decodeFromBase64(item.key);
+            const ciphertext = decodeFromBase64(item.value);
+            return {
+                seeker,
+                ciphertext,
+            };
+        });
+    }
+    async sendMessage(message) {
+        const url = `${this.baseUrl}${MESSAGES_ENDPOINT}/`;
+        const response = await this.makeRequest(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                key: encodeToBase64(message.seeker),
+                value: encodeToBase64(message.ciphertext),
+            }),
+        });
+        if (!response.success) {
+            throw new Error(response.error || 'Failed to send message');
+        }
+    }
+    async sendAnnouncement(announcement) {
+        const url = `${this.baseUrl}${BULLETIN_ENDPOINT}`;
+        const response = await this.makeRequest(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                data: encodeToBase64(announcement),
+            }),
+        });
+        if (!response.success || !response.data) {
+            throw new Error(response.error || 'Failed to broadcast outgoing session');
+        }
+        return response.data.counter;
+    }
+    async fetchAnnouncements(limit = 50, cursor) {
+        const params = new URLSearchParams();
+        params.set('limit', limit.toString());
+        // Always pass 'after' parameter. If cursor is undefined, use '0' to fetch from the beginning.
+        // This ensures pagination works correctly: after=0 gets counters 1-20, after=20 gets 21-40, etc.
+        params.set('after', cursor ?? '0');
+        const url = `${this.baseUrl}${BULLETIN_ENDPOINT}?${params.toString()}`;
+        const response = await this.makeRequest(url, {
+            method: 'GET',
+        });
+        if (!response.success || response.data == null) {
+            throw new Error(response.error || 'Failed to fetch announcements');
+        }
+        return response.data.map(item => ({
+            counter: item.counter,
+            data: decodeFromBase64(item.data),
+        }));
+    }
+    async fetchPublicKeyByUserId(userId) {
+        const response = await this.makeRequest(`${this.baseUrl}/auth/retrieve`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ key: encodeToBase64(userId) }),
+        });
+        if (!response.success || !response.data) {
+            throw new Error(response.error || 'Failed to fetch public key');
+        }
+        if (!response.data.value) {
+            throw new Error('Public key not found');
+        }
+        return response.data.value;
+    }
+    async postPublicKey(base64PublicKeys) {
+        const url = `${this.baseUrl}/auth`;
+        const response = await this.makeRequest(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ value: base64PublicKeys }),
+        });
+        if (!response.success || !response.data) {
+            const errorMessage = response.error || 'Failed to store public key';
+            throw new Error(errorMessage);
+        }
+        return response.data.value;
+    }
+    async makeRequest(url, options) {
+        let lastError = null;
+        for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const response = await fetch(url, {
+                    ...options,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                }
+                const data = await response.json();
+                return { success: true, data };
+            }
+            catch (error) {
+                lastError = error;
+                console.warn(`Request attempt ${attempt} failed:`, error);
+                if (attempt < this.retryAttempts) {
+                    // Exponential backoff
+                    const delay = Math.pow(2, attempt) * 1000;
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+        }
+        return {
+            success: false,
+            error: lastError?.message || 'Request failed after all retry attempts',
+        };
+    }
+    async changeNode(nodeUrl) {
+        return {
+            success: true,
+            data: 'This message protocol provider use a single node, so changing the node to ' +
+                nodeUrl +
+                ' is not supported',
+        };
+    }
+}

package/dist/api/messageProtocol/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Message Protocol Types and Interfaces
+ *
+ * Defines the core types and interfaces for message protocol operations.
+ */
+export type BulletinItem = {
+    counter: string;
+    data: Uint8Array;
+};
+export interface EncryptedMessage {
+    seeker: Uint8Array;
+    ciphertext: Uint8Array;
+}
+export interface MessageProtocolResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Abstract interface for message protocol operations
+ */
+export interface IMessageProtocol {
+    /**
+     * Fetch encrypted messages for the provided set of seeker read keys
+     */
+    fetchMessages(seekers: Uint8Array[]): Promise<EncryptedMessage[]>;
+    /**
+     * Send an encrypted message to the key-value store
+     */
+    sendMessage(message: EncryptedMessage): Promise<void>;
+    /**
+     * Broadcast an outgoing session announcement produced by WASM.
+     * Returns the bulletin counter provided by the API.
+     */
+    sendAnnouncement(announcement: Uint8Array): Promise<string>;
+    /**
+     * Fetch incoming discussion announcements from the bulletin storage.
+     * Returns raw announcement bytes as provided by the API.
+     * @param limit - Maximum number of announcements to fetch (default: 20)
+     * @param cursor - Optional cursor (counter) to fetch announcements after this value
+     */
+    fetchAnnouncements(limit?: number, cursor?: string): Promise<BulletinItem[]>;
+    /**
+     * Fetch public key by userId hash (base64 string)
+     * @param userId - Decoded userId bytes
+     * @returns Base64-encoded public keys
+     */
+    fetchPublicKeyByUserId(userId: Uint8Array): Promise<string>;
+    /**
+     * Store public key in the auth API
+     * @param base64PublicKeys - Base64-encoded public keys
+     * @returns The hash key (hex string) returned by the API
+     */
+    postPublicKey(base64PublicKeys: string): Promise<string>;
+    /**
+     * Change the current node provider
+     * @param nodeUrl - The URL of the new node
+     * @returns MessageProtocolResponse with the new node information
+     */
+    changeNode(nodeUrl?: string): Promise<MessageProtocolResponse>;
+}

package/dist/api/messageProtocol/types.js

@@ -0,0 +1,6 @@
+/**
+ * Message Protocol Types and Interfaces
+ *
+ * Defines the core types and interfaces for message protocol operations.
+ */
+export {};

package/dist/assets/generated/wasm/README.md

@@ -0,0 +1,281 @@
+# Gossip WASM - WebAssembly Bindings
+
+This crate provides WebAssembly bindings for the Gossip secure messaging system, exposing the SessionManager and Auth facilities to JavaScript/TypeScript applications.
+
+## Features
+
+- **Session Management**: Create, persist, and manage encrypted messaging sessions
+- **Authentication**: Generate and manage cryptographic keys from passphrases
+- **Post-Quantum Security**: Uses ML-KEM and ML-DSA for quantum-resistant cryptography
+- **Encrypted State**: Secure serialization and deserialization of session state
+- **Seeker-based Addressing**: Messages use hashed Massa public keys for efficient lookups
+
+## Building
+
+### Prerequisites
+
+- Rust toolchain with `wasm32-unknown-unknown` target
+- wasm-pack (optional, for generating npm package)
+
+### Build with Cargo
+
+```bash
+cargo build --target wasm32-unknown-unknown --release
+```
+
+The compiled WASM module will be at:
+
+```
+../target/wasm32-unknown-unknown/release/gossip_wasm.wasm
+```
+
+### Build with wasm-pack
+
+For a complete npm-ready package with TypeScript definitions:
+
+```bash
+wasm-pack build --target web
+```
+
+## Usage
+
+### JavaScript/TypeScript
+
+```typescript
+import init, {
+  SessionManagerWrapper,
+  SessionConfig,
+  generate_user_keys,
+  EncryptionKey,
+} from './gossip_wasm';
+
+// Initialize WASM
+await init();
+
+// Generate user keys from passphrase
+const keys = generate_user_keys('my secure passphrase');
+const publicKeys = keys.public_keys();
+const secretKeys = keys.secret_keys();
+const userId = publicKeys.derive_id();
+
+// Create session manager with default configuration
+const config = SessionConfig.new_default();
+const manager = new SessionManagerWrapper(config);
+
+// Establish session with peer
+const peerKeys = generate_user_keys('peer passphrase');
+const userData = new TextEncoder().encode('contact_request'); // Optional user data
+const announcement = manager.establish_outgoing_session(
+  peerKeys.public_keys(),
+  publicKeys,
+  secretKeys,
+  userData
+);
+// Publish announcement to blockchain...
+
+// Feed incoming announcement from peer
+const result = manager.feed_incoming_announcement(
+  announcementBytes,
+  publicKeys,
+  secretKeys
+);
+if (result) {
+  console.log('Announcer public keys:', result.announcer_public_keys);
+  console.log('Timestamp:', result.timestamp);
+  console.log('User data:', new TextDecoder().decode(result.user_data));
+}
+
+// Send a message (raw bytes)
+const messageBytes = new TextEncoder().encode('Hello!');
+const peerId = peerKeys.public_keys().derive_id();
+const sendOutput = manager.send_message(peerId, messageBytes);
+if (sendOutput) {
+  // Publish sendOutput.seeker and sendOutput.data to blockchain
+  console.log('Seeker:', sendOutput.seeker);
+  console.log('Data length:', sendOutput.data.length);
+}
+
+// Check for incoming messages
+const seekers = manager.get_message_board_read_keys();
+for (let i = 0; i < seekers.length; i++) {
+  const seeker = seekers.get(i);
+  // Read from blockchain using seeker...
+  const received = manager.feed_incoming_message_board_read(
+    seeker,
+    data, // encrypted message data
+    secretKeys
+  );
+  if (received) {
+    console.log('Received:', new TextDecoder().decode(received.message));
+    console.log('Timestamp:', received.timestamp);
+    // Check acknowledged seekers
+    const acks = received.acknowledged_seekers;
+    for (let j = 0; j < acks.length; j++) {
+      console.log('Acknowledged:', acks.get(j));
+    }
+  }
+}
+
+// Persist session state
+const encryptionKey = EncryptionKey.generate();
+const encrypted = manager.to_encrypted_blob(encryptionKey);
+// Save encrypted blob to storage...
+
+// Restore session state
+const restored = SessionManagerWrapper.from_encrypted_blob(
+  encrypted,
+  encryptionKey
+);
+```
+
+### Custom Configuration
+
+```typescript
+const config = new SessionConfig(
+  604800000, // max_incoming_announcement_age_millis (1 week)
+  60000, // max_incoming_announcement_future_millis (1 minute)
+  604800000, // max_incoming_message_age_millis (1 week)
+  60000, // max_incoming_message_future_millis (1 minute)
+  604800000, // max_session_inactivity_millis (1 week)
+  86400000, // keep_alive_interval_millis (1 day)
+  10000 // max_session_lag_length
+);
+```
+
+## API Reference
+
+### AEAD Encryption Functions
+
+Direct access to AES-256-SIV authenticated encryption:
+
+- `aead_encrypt(key: EncryptionKey, nonce: Nonce, plaintext: Uint8Array, aad: Uint8Array)`: Encrypt data
+- `aead_decrypt(key: EncryptionKey, nonce: Nonce, ciphertext: Uint8Array, aad: Uint8Array)`: Decrypt data
+
+#### AEAD Example
+
+```typescript
+import {
+  EncryptionKey,
+  Nonce,
+  aead_encrypt,
+  aead_decrypt,
+} from './gossip_wasm';
+
+// Generate key and nonce
+const key = EncryptionKey.generate();
+const nonce = Nonce.generate();
+
+// Encrypt some data
+const plaintext = new TextEncoder().encode('Secret message');
+const aad = new TextEncoder().encode('context info'); // Additional authenticated data
+const ciphertext = aead_encrypt(key, nonce, plaintext, aad);
+
+// Decrypt
+const decrypted = aead_decrypt(key, nonce, ciphertext, aad);
+if (decrypted) {
+  console.log('Success:', new TextDecoder().decode(decrypted));
+} else {
+  console.error('Decryption failed - tampering detected!');
+}
+```
+
+**Security Notes:**
+
+- Nonces should be unique per encryption (16 bytes)
+- AAD (Additional Authenticated Data) is authenticated but NOT encrypted
+- AES-SIV is nonce-misuse resistant - reusing nonces only leaks if plaintexts are identical
+- Keys are 64 bytes (512 bits) for AES-256-SIV
+
+### SessionManagerWrapper
+
+Main class for managing messaging sessions.
+
+- `new(config: SessionConfig)`: Create new session manager
+- `from_encrypted_blob(blob: Uint8Array, key: EncryptionKey)`: Restore from encrypted state
+- `to_encrypted_blob(key: EncryptionKey)`: Serialize to encrypted blob
+- `establish_outgoing_session(peer_pk, our_pk, our_sk, user_data: Uint8Array)`: Initiate session with peer, including optional user data (returns announcement bytes)
+- `feed_incoming_announcement(bytes, our_pk, our_sk)`: Process incoming announcement (returns AnnouncementResult with announcer's public keys and user data, or undefined)
+- `send_message(peer_id: Uint8Array, message_contents: Uint8Array)`: Send raw message bytes to peer
+- `feed_incoming_message_board_read(seeker, data, our_sk)`: Process incoming messages
+- `get_message_board_read_keys()`: Get seekers to monitor for incoming messages
+- `peer_list()`: Get all peer IDs
+- `peer_session_status(peer_id: Uint8Array)`: Get session status
+- `peer_discard(peer_id: Uint8Array)`: Remove peer
+- `refresh()`: Refresh sessions and get keep-alive announcement list
+
+### AnnouncementResult
+
+Result from processing an incoming announcement:
+
+- `announcer_public_keys(): UserPublicKeys`: The public keys of the peer who sent the announcement
+- `timestamp(): number`: Unix timestamp in milliseconds when the announcement was created
+- `user_data(): Uint8Array`: Arbitrary user data embedded in the announcement (can be empty)
+
+**Use Cases for User Data:**
+
+- Contact requests with metadata
+- Version information
+- Application-specific handshake data
+- Display names or profile information
+- Protocol negotiation parameters
+
+**⚠️ Security Warning:**
+
+The user_data in announcements has **reduced security compared to regular messages**:
+
+- ✅ **Plausible deniability preserved**: The user_data is not cryptographically signed, so the sender can deny specific content
+- ❌ **No post-compromise secrecy**: If long-term keys are compromised, past announcements can be decrypted
+
+**Recommendation**: Use user_data for non-highly-sensitive metadata. Send truly sensitive information through regular messages after the session is established.
+
+### SendMessageOutput
+
+Output from sending a message:
+
+- `seeker(): Uint8Array`: Database key for message lookup on message board
+- `data(): Uint8Array`: Encrypted message data to publish
+- `timestamp(): number`: Message timestamp (milliseconds since Unix epoch)
+
+### ReceiveMessageOutput
+
+Output from receiving a message:
+
+- `message(): Uint8Array`: Decrypted message contents
+- `timestamp(): number`: Message timestamp (milliseconds since Unix epoch)
+- `acknowledged_seekers()`: Array of seekers that were acknowledged
+
+### Auth Functions
+
+- `generate_user_keys(passphrase: string)`: Generate keys from passphrase using password KDF
+
+### Other Classes
+
+- `SessionConfig`: Session manager configuration
+- `EncryptionKey`: AES-256-SIV key (64 bytes)
+  - `generate()`: Generate random key
+  - `from_bytes(bytes: Uint8Array)`: Create from bytes
+  - `to_bytes()`: Get raw bytes
+- `Nonce`: AES-256-SIV nonce (16 bytes)
+  - `generate()`: Generate random nonce
+  - `from_bytes(bytes: Uint8Array)`: Create from bytes
+  - `to_bytes()`: Get raw bytes
+- `UserPublicKeys`: User's public keys
+  - `derive_id()`: Get user ID (32 bytes)
+  - `to_bytes()`: Serialize to bytes
+- `UserSecretKeys`: User's secret keys
+- `SessionStatus`: Enum for session states (Active, Inactive, etc.)
+
+## Architecture
+
+The Gossip system uses a multi-layer architecture:
+
+1. **Crypto Primitives**: ML-KEM (post-quantum KEM), ML-DSA (post-quantum signatures), AES-SIV (AEAD)
+2. **Agraphon Protocol**: Double-ratchet encryption with forward secrecy and post-compromise security
+3. **Session Layer**: Manages Agraphon sessions with seeker-based addressing using hashed Massa public keys
+4. **Session Manager**: High-level API for multi-peer messaging with session lifecycle management
+
+Messages are identified by "seekers" - database keys derived from hashing ephemeral Massa public keys. This allows:
+
+- Efficient message lookup on public message boards
+- Privacy (seekers don't reveal sender/recipient identity)
+- Unlinkability (each message uses a fresh keypair)