@quilibrium/quorum-shared 2.1.0-1

package/src/crypto/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Crypto module exports
+ */
+
+export type {
+  // Key types
+  Ed448Keypair,
+  X448Keypair,
+  Keypair,
+  // Message types
+  MessageCiphertext,
+  P2PChannelEnvelope,
+  // X3DH
+  SenderX3DHParams,
+  ReceiverX3DHParams,
+  // Double ratchet
+  NewDoubleRatchetParams,
+  DoubleRatchetStateAndMessage,
+  DoubleRatchetStateAndEnvelope,
+  // Triple ratchet
+  PeerInfo,
+  NewTripleRatchetParams,
+  TripleRatchetStateAndMetadata,
+  TripleRatchetStateAndMessage,
+  TripleRatchetStateAndEnvelope,
+  // Initialization envelope
+  InitializationEnvelope,
+  // Inbox encryption
+  InboxMessageEncryptRequest,
+  InboxMessageDecryptRequest,
+  // Provider interface
+  CryptoProvider,
+} from './types';
+
+// Encryption state types and storage interface
+export type {
+  // Device and recipient types
+  DeviceKeys,
+  RecipientInfo,
+  EncryptedEnvelope,
+  // Storage types
+  KeyValueStorageProvider,
+  SendingInbox,
+  ReceivingInbox,
+  EncryptionState,
+  InboxMapping,
+  LatestState,
+  ConversationInboxKeypair,
+  EncryptionStateStorageInterface,
+} from './encryption-state';
+export { ENCRYPTION_STORAGE_KEYS } from './encryption-state';
+
+// WASM implementation (for desktop/web)
+export { WasmCryptoProvider } from './wasm-provider';
+export type { ChannelWasmModule } from './wasm-provider';

package/src/crypto/types.ts

@@ -0,0 +1,307 @@
+/**
+ * Crypto types and CryptoProvider interface
+ *
+ * Platform-agnostic cryptographic operations for E2E encryption.
+ * Implementations:
+ * - WASM (desktop/web): Uses channel-wasm bindings
+ * - Native (iOS/Android): Uses uniffi-generated bindings
+ */
+
+// ============ Key Types ============
+
+export interface Ed448Keypair {
+  type: 'ed448';
+  public_key: number[];
+  private_key: number[];
+}
+
+export interface X448Keypair {
+  type: 'x448';
+  public_key: number[];
+  private_key: number[];
+}
+
+export type Keypair = Ed448Keypair | X448Keypair;
+
+// ============ Message Ciphertext ============
+
+export interface MessageCiphertext {
+  ciphertext: string;
+  initialization_vector: string;
+  associated_data?: string;
+}
+
+export interface P2PChannelEnvelope {
+  protocol_identifier: number;
+  message_header: MessageCiphertext;
+  message_body: MessageCiphertext;
+}
+
+// ============ X3DH Key Agreement ============
+
+export interface SenderX3DHParams {
+  sending_identity_private_key: number[];
+  sending_ephemeral_private_key: number[];
+  receiving_identity_key: number[];
+  receiving_signed_pre_key: number[];
+  session_key_length: number;
+}
+
+export interface ReceiverX3DHParams {
+  sending_identity_private_key: number[];
+  sending_signed_private_key: number[];
+  receiving_identity_key: number[];
+  receiving_ephemeral_key: number[];
+  session_key_length: number;
+}
+
+// ============ Double Ratchet ============
+
+export interface NewDoubleRatchetParams {
+  session_key: number[];
+  sending_header_key: number[];
+  next_receiving_header_key: number[];
+  is_sender: boolean;
+  sending_ephemeral_private_key: number[];
+  receiving_ephemeral_key: number[];
+}
+
+export interface DoubleRatchetStateAndMessage {
+  ratchet_state: string;
+  message: number[];
+}
+
+export interface DoubleRatchetStateAndEnvelope {
+  ratchet_state: string;
+  envelope: string;
+}
+
+// ============ Triple Ratchet ============
+
+export interface PeerInfo {
+  public_key: number[];
+  identity_public_key: number[];
+  signed_pre_public_key: number[];
+}
+
+export interface NewTripleRatchetParams {
+  peers: number[][];
+  peer_key: number[];
+  identity_key: number[];
+  signed_pre_key: number[];
+  threshold: number;
+  async_dkg_ratchet: boolean;
+}
+
+export interface TripleRatchetStateAndMetadata {
+  ratchet_state: string;
+  metadata: Record<string, string>;
+}
+
+export interface TripleRatchetStateAndMessage {
+  ratchet_state: string;
+  message: number[];
+}
+
+export interface TripleRatchetStateAndEnvelope {
+  ratchet_state: string;
+  envelope: string;
+}
+
+// ============ Initialization Envelope ============
+
+/**
+ * InitializationEnvelope - Contains sender info for first message in a session
+ *
+ * This is the format BEFORE sealing. The ephemeral_public_key is NOT included here -
+ * it goes at the TOP LEVEL of the SealedMessage, and the SAME ephemeral key is used for both:
+ * 1. Sealing the envelope (inbox encryption)
+ * 2. X3DH session establishment
+ *
+ * After unsealing, the ephemeral_public_key is added back to create UnsealedEnvelope
+ * (see transport/websocket.ts)
+ */
+export interface InitializationEnvelope {
+  /** Sender's user address */
+  user_address: string;
+  /** Sender's display name */
+  display_name?: string;
+  /** Sender's icon URL */
+  user_icon?: string;
+  /** Inbox address for sending replies */
+  return_inbox_address: string;
+  /** X448 encryption key for the return inbox (hex) */
+  return_inbox_encryption_key: string;
+  /** Ed448 public key for the return inbox (hex) */
+  return_inbox_public_key: string;
+  /** Ed448 private key for the return inbox (hex) - shared so recipient can sign replies */
+  return_inbox_private_key: string;
+  /** Sender's identity public key for X3DH (hex) */
+  identity_public_key: string;
+  /** Session/conversation tag (typically the return inbox address) */
+  tag: string;
+  /** The Double Ratchet encrypted message envelope */
+  message: string;
+  /** Message type (e.g., 'direct') */
+  type: string;
+}
+
+// ============ Inbox Message Encryption ============
+
+export interface InboxMessageEncryptRequest {
+  inbox_public_key: number[];
+  ephemeral_private_key: number[];
+  plaintext: number[];
+}
+
+export interface InboxMessageDecryptRequest {
+  inbox_private_key: number[];
+  ephemeral_public_key: number[];
+  ciphertext: MessageCiphertext;
+}
+
+// ============ CryptoProvider Interface ============
+
+/**
+ * CryptoProvider - Platform-agnostic interface for cryptographic operations
+ *
+ * This interface abstracts the underlying crypto implementation,
+ * allowing the same code to work with WASM (desktop) or native modules (mobile).
+ *
+ * All methods are async to support both synchronous WASM and async native bridges.
+ * State is serialized as JSON strings for cross-platform compatibility.
+ */
+export interface CryptoProvider {
+  // ============ Key Generation ============
+
+  /**
+   * Generate an X448 keypair for encryption
+   */
+  generateX448(): Promise<X448Keypair>;
+
+  /**
+   * Generate an Ed448 keypair for signing
+   */
+  generateEd448(): Promise<Ed448Keypair>;
+
+  /**
+   * Derive public key from X448 private key
+   * @param privateKey Base64-encoded private key
+   * @returns Base64-encoded public key
+   */
+  getPublicKeyX448(privateKey: string): Promise<string>;
+
+  /**
+   * Derive public key from Ed448 private key
+   * @param privateKey Base64-encoded private key
+   * @returns Base64-encoded public key
+   */
+  getPublicKeyEd448(privateKey: string): Promise<string>;
+
+  // ============ X3DH Key Agreement ============
+
+  /**
+   * Perform sender-side X3DH key agreement
+   * @returns Base64-encoded session key (96 bytes: 32 session + 32 sending header + 32 receiving header)
+   */
+  senderX3DH(params: SenderX3DHParams): Promise<string>;
+
+  /**
+   * Perform receiver-side X3DH key agreement
+   * @returns Base64-encoded session key (96 bytes)
+   */
+  receiverX3DH(params: ReceiverX3DHParams): Promise<string>;
+
+  // ============ Double Ratchet ============
+
+  /**
+   * Initialize a new double ratchet session
+   * @returns JSON-serialized ratchet state
+   */
+  newDoubleRatchet(params: NewDoubleRatchetParams): Promise<string>;
+
+  /**
+   * Encrypt a message using double ratchet
+   * @returns Updated state and encrypted envelope
+   */
+  doubleRatchetEncrypt(
+    stateAndMessage: DoubleRatchetStateAndMessage
+  ): Promise<DoubleRatchetStateAndEnvelope>;
+
+  /**
+   * Decrypt a message using double ratchet
+   * @returns Updated state and decrypted message
+   */
+  doubleRatchetDecrypt(
+    stateAndEnvelope: DoubleRatchetStateAndEnvelope
+  ): Promise<DoubleRatchetStateAndMessage>;
+
+  // ============ Triple Ratchet ============
+
+  /**
+   * Initialize a new triple ratchet session for group messaging
+   * @returns Initial state and DKG metadata
+   */
+  newTripleRatchet(params: NewTripleRatchetParams): Promise<TripleRatchetStateAndMetadata>;
+
+  /**
+   * Triple ratchet DKG round 1 - Generate polynomial fragments
+   */
+  tripleRatchetInitRound1(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata>;
+
+  /**
+   * Triple ratchet DKG round 2 - Receive fragments, compute ZK commitment
+   */
+  tripleRatchetInitRound2(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata>;
+
+  /**
+   * Triple ratchet DKG round 3 - Receive commitments, compute ZK reveal
+   */
+  tripleRatchetInitRound3(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata>;
+
+  /**
+   * Triple ratchet DKG round 4 - Verify proofs, reconstruct group key
+   */
+  tripleRatchetInitRound4(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata>;
+
+  /**
+   * Encrypt a message for the group using triple ratchet
+   */
+  tripleRatchetEncrypt(
+    stateAndMessage: TripleRatchetStateAndMessage
+  ): Promise<TripleRatchetStateAndEnvelope>;
+
+  /**
+   * Decrypt a group message using triple ratchet
+   */
+  tripleRatchetDecrypt(
+    stateAndEnvelope: TripleRatchetStateAndEnvelope
+  ): Promise<TripleRatchetStateAndMessage>;
+
+  /**
+   * Handle group membership changes
+   */
+  tripleRatchetResize(state: TripleRatchetStateAndMetadata): Promise<TripleRatchetStateAndMetadata>;
+
+  // ============ Inbox Message Encryption ============
+
+  /**
+   * Encrypt a message for an inbox (sealed sender / ECIES-style)
+   * @returns Base64-encoded sealed message
+   */
+  encryptInboxMessage(request: InboxMessageEncryptRequest): Promise<string>;
+
+  /**
+   * Decrypt a sealed inbox message
+   * @returns Decrypted plaintext as byte array
+   */
+  decryptInboxMessage(request: InboxMessageDecryptRequest): Promise<number[]>;
+}

package/src/crypto/wasm-provider.ts

@@ -0,0 +1,298 @@
+/**
+ * WASM CryptoProvider implementation
+ *
+ * Wraps the channel-wasm WASM module to implement the CryptoProvider interface.
+ * Used by desktop/web applications.
+ *
+ * Note: This file imports from the WASM module dynamically to avoid bundling
+ * issues in environments that don't support WASM.
+ */
+
+import type {
+  CryptoProvider,
+  Ed448Keypair,
+  X448Keypair,
+  SenderX3DHParams,
+  ReceiverX3DHParams,
+  NewDoubleRatchetParams,
+  DoubleRatchetStateAndMessage,
+  DoubleRatchetStateAndEnvelope,
+  NewTripleRatchetParams,
+  TripleRatchetStateAndMetadata,
+  TripleRatchetStateAndMessage,
+  TripleRatchetStateAndEnvelope,
+  InboxMessageEncryptRequest,
+  InboxMessageDecryptRequest,
+} from './types';
+
+/**
+ * Interface for the WASM module functions
+ * This matches the exports from channel-wasm
+ */
+export interface ChannelWasmModule {
+  js_generate_x448(): string;
+  js_generate_ed448(): string;
+  js_get_pubkey_x448(key: string): string;
+  js_get_pubkey_ed448(key: string): string;
+  js_sign_ed448(key: string, message: string): string;
+  js_verify_ed448(publicKey: string, message: string, signature: string): string;
+  js_sender_x3dh(input: string): string;
+  js_receiver_x3dh(input: string): string;
+  js_new_double_ratchet(params: string): string;
+  js_double_ratchet_encrypt(params: string): string;
+  js_double_ratchet_decrypt(params: string): string;
+  js_new_triple_ratchet(params: string): string;
+  js_triple_ratchet_init_round_1(params: string): string;
+  js_triple_ratchet_init_round_2(params: string): string;
+  js_triple_ratchet_init_round_3(params: string): string;
+  js_triple_ratchet_init_round_4(params: string): string;
+  js_triple_ratchet_encrypt(params: string): string;
+  js_triple_ratchet_decrypt(params: string): string;
+  js_triple_ratchet_resize(params: string): string;
+  js_encrypt_inbox_message(input: string): string;
+  js_decrypt_inbox_message(input: string): string;
+}
+
+/**
+ * Parse WASM result and check for errors
+ * WASM functions return error strings on failure
+ */
+function parseWasmResult<T>(result: string): T {
+  // Check for common error patterns
+  if (
+    result.startsWith('invalid') ||
+    result.startsWith('error') ||
+    result.includes('failed') ||
+    result.includes('Error')
+  ) {
+    throw new Error(result);
+  }
+
+  try {
+    return JSON.parse(result) as T;
+  } catch {
+    // If it's not JSON, it might be a quoted string or error
+    if (result.startsWith('"') && result.endsWith('"')) {
+      // Remove quotes from string results
+      return result.slice(1, -1) as unknown as T;
+    }
+    throw new Error(`Failed to parse WASM result: ${result}`);
+  }
+}
+
+/**
+ * WasmCryptoProvider - Implements CryptoProvider using channel-wasm
+ */
+export class WasmCryptoProvider implements CryptoProvider {
+  private wasm: ChannelWasmModule;
+
+  constructor(wasmModule: ChannelWasmModule) {
+    this.wasm = wasmModule;
+  }
+
+  // ============ Key Generation ============
+
+  async generateX448(): Promise<X448Keypair> {
+    const result = this.wasm.js_generate_x448();
+    const keypair = parseWasmResult<{ public_key: number[]; private_key: number[] }>(result);
+    return {
+      type: 'x448',
+      public_key: keypair.public_key,
+      private_key: keypair.private_key,
+    };
+  }
+
+  async generateEd448(): Promise<Ed448Keypair> {
+    const result = this.wasm.js_generate_ed448();
+    const keypair = parseWasmResult<{ public_key: number[]; private_key: number[] }>(result);
+    return {
+      type: 'ed448',
+      public_key: keypair.public_key,
+      private_key: keypair.private_key,
+    };
+  }
+
+  async getPublicKeyX448(privateKey: string): Promise<string> {
+    const result = this.wasm.js_get_pubkey_x448(privateKey);
+    return parseWasmResult<string>(result);
+  }
+
+  async getPublicKeyEd448(privateKey: string): Promise<string> {
+    const result = this.wasm.js_get_pubkey_ed448(privateKey);
+    return parseWasmResult<string>(result);
+  }
+
+  // ============ X3DH Key Agreement ============
+
+  async senderX3DH(params: SenderX3DHParams): Promise<string> {
+    const input = JSON.stringify({
+      sending_identity_private_key: params.sending_identity_private_key,
+      sending_ephemeral_private_key: params.sending_ephemeral_private_key,
+      receiving_identity_key: params.receiving_identity_key,
+      receiving_signed_pre_key: params.receiving_signed_pre_key,
+      session_key_length: params.session_key_length,
+    });
+    const result = this.wasm.js_sender_x3dh(input);
+    if (result.startsWith('invalid') || result.includes('error')) {
+      throw new Error(result);
+    }
+    return result;
+  }
+
+  async receiverX3DH(params: ReceiverX3DHParams): Promise<string> {
+    const input = JSON.stringify({
+      sending_identity_private_key: params.sending_identity_private_key,
+      sending_signed_private_key: params.sending_signed_private_key,
+      receiving_identity_key: params.receiving_identity_key,
+      receiving_ephemeral_key: params.receiving_ephemeral_key,
+      session_key_length: params.session_key_length,
+    });
+    const result = this.wasm.js_receiver_x3dh(input);
+    if (result.startsWith('invalid') || result.includes('error')) {
+      throw new Error(result);
+    }
+    return result;
+  }
+
+  // ============ Double Ratchet ============
+
+  async newDoubleRatchet(params: NewDoubleRatchetParams): Promise<string> {
+    const input = JSON.stringify({
+      session_key: params.session_key,
+      sending_header_key: params.sending_header_key,
+      next_receiving_header_key: params.next_receiving_header_key,
+      is_sender: params.is_sender,
+      sending_ephemeral_private_key: params.sending_ephemeral_private_key,
+      receiving_ephemeral_key: params.receiving_ephemeral_key,
+    });
+    const result = this.wasm.js_new_double_ratchet(input);
+    if (result.startsWith('invalid') || result.includes('error')) {
+      throw new Error(result);
+    }
+    return result;
+  }
+
+  async doubleRatchetEncrypt(
+    stateAndMessage: DoubleRatchetStateAndMessage
+  ): Promise<DoubleRatchetStateAndEnvelope> {
+    const input = JSON.stringify({
+      ratchet_state: stateAndMessage.ratchet_state,
+      message: stateAndMessage.message,
+    });
+    const result = this.wasm.js_double_ratchet_encrypt(input);
+    return parseWasmResult<DoubleRatchetStateAndEnvelope>(result);
+  }
+
+  async doubleRatchetDecrypt(
+    stateAndEnvelope: DoubleRatchetStateAndEnvelope
+  ): Promise<DoubleRatchetStateAndMessage> {
+    const input = JSON.stringify({
+      ratchet_state: stateAndEnvelope.ratchet_state,
+      envelope: stateAndEnvelope.envelope,
+    });
+    const result = this.wasm.js_double_ratchet_decrypt(input);
+    return parseWasmResult<DoubleRatchetStateAndMessage>(result);
+  }
+
+  // ============ Triple Ratchet ============
+
+  async newTripleRatchet(params: NewTripleRatchetParams): Promise<TripleRatchetStateAndMetadata> {
+    const input = JSON.stringify({
+      peers: params.peers,
+      peer_key: params.peer_key,
+      identity_key: params.identity_key,
+      signed_pre_key: params.signed_pre_key,
+      threshold: params.threshold,
+      async_dkg_ratchet: params.async_dkg_ratchet,
+    });
+    const result = this.wasm.js_new_triple_ratchet(input);
+    return parseWasmResult<TripleRatchetStateAndMetadata>(result);
+  }
+
+  async tripleRatchetInitRound1(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata> {
+    const input = JSON.stringify(state);
+    const result = this.wasm.js_triple_ratchet_init_round_1(input);
+    return parseWasmResult<TripleRatchetStateAndMetadata>(result);
+  }
+
+  async tripleRatchetInitRound2(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata> {
+    const input = JSON.stringify(state);
+    const result = this.wasm.js_triple_ratchet_init_round_2(input);
+    return parseWasmResult<TripleRatchetStateAndMetadata>(result);
+  }
+
+  async tripleRatchetInitRound3(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata> {
+    const input = JSON.stringify(state);
+    const result = this.wasm.js_triple_ratchet_init_round_3(input);
+    return parseWasmResult<TripleRatchetStateAndMetadata>(result);
+  }
+
+  async tripleRatchetInitRound4(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata> {
+    const input = JSON.stringify(state);
+    const result = this.wasm.js_triple_ratchet_init_round_4(input);
+    return parseWasmResult<TripleRatchetStateAndMetadata>(result);
+  }
+
+  async tripleRatchetEncrypt(
+    stateAndMessage: TripleRatchetStateAndMessage
+  ): Promise<TripleRatchetStateAndEnvelope> {
+    const input = JSON.stringify({
+      ratchet_state: stateAndMessage.ratchet_state,
+      message: stateAndMessage.message,
+    });
+    const result = this.wasm.js_triple_ratchet_encrypt(input);
+    return parseWasmResult<TripleRatchetStateAndEnvelope>(result);
+  }
+
+  async tripleRatchetDecrypt(
+    stateAndEnvelope: TripleRatchetStateAndEnvelope
+  ): Promise<TripleRatchetStateAndMessage> {
+    const input = JSON.stringify({
+      ratchet_state: stateAndEnvelope.ratchet_state,
+      envelope: stateAndEnvelope.envelope,
+    });
+    const result = this.wasm.js_triple_ratchet_decrypt(input);
+    return parseWasmResult<TripleRatchetStateAndMessage>(result);
+  }
+
+  async tripleRatchetResize(
+    state: TripleRatchetStateAndMetadata
+  ): Promise<TripleRatchetStateAndMetadata> {
+    const input = JSON.stringify(state);
+    const result = this.wasm.js_triple_ratchet_resize(input);
+    return parseWasmResult<TripleRatchetStateAndMetadata>(result);
+  }
+
+  // ============ Inbox Message Encryption ============
+
+  async encryptInboxMessage(request: InboxMessageEncryptRequest): Promise<string> {
+    const input = JSON.stringify({
+      inbox_public_key: request.inbox_public_key,
+      ephemeral_private_key: request.ephemeral_private_key,
+      plaintext: request.plaintext,
+    });
+    const result = this.wasm.js_encrypt_inbox_message(input);
+    if (result.startsWith('invalid') || result.includes('error')) {
+      throw new Error(result);
+    }
+    return result;
+  }
+
+  async decryptInboxMessage(request: InboxMessageDecryptRequest): Promise<number[]> {
+    const input = JSON.stringify({
+      inbox_private_key: request.inbox_private_key,
+      ephemeral_public_key: request.ephemeral_public_key,
+      ciphertext: request.ciphertext,
+    });
+    const result = this.wasm.js_decrypt_inbox_message(input);
+    return parseWasmResult<number[]>(result);
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared React Query hooks
+ */
+
+// Query keys
+export { queryKeys } from './keys';
+export type {
+  SpacesKey,
+  SpaceDetailKey,
+  ChannelsKey,
+  MessagesInfiniteKey,
+} from './keys';
+
+// Space hooks
+export { useSpaces, useSpace, useSpaceMembers } from './useSpaces';
+export type { UseSpacesOptions, UseSpaceOptions } from './useSpaces';
+
+// Channel hooks
+export { useChannels, flattenChannels, findChannel } from './useChannels';
+export type { UseChannelsOptions } from './useChannels';
+
+// Message hooks
+export {
+  useMessages,
+  flattenMessages,
+  useInvalidateMessages,
+} from './useMessages';
+export type { UseMessagesOptions } from './useMessages';
+
+// Mutations (to be added)
+export * from './mutations';