@quilibrium/quorum-shared 2.1.0-1

package/src/hooks/useSpaces.ts

@@ -0,0 +1,60 @@
+/**
+ * useSpaces hook
+ *
+ * Fetches and caches space data with offline support
+ */
+
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import type { Space } from '../types';
+import type { StorageAdapter } from '../storage';
+import { queryKeys } from './keys';
+
+export interface UseSpacesOptions {
+  storage: StorageAdapter;
+  enabled?: boolean;
+}
+
+export function useSpaces({ storage, enabled = true }: UseSpacesOptions) {
+  return useQuery({
+    queryKey: queryKeys.spaces.all,
+    queryFn: async (): Promise<Space[]> => {
+      return storage.getSpaces();
+    },
+    enabled,
+    staleTime: 1000 * 60 * 5, // 5 minutes
+  });
+}
+
+export interface UseSpaceOptions {
+  storage: StorageAdapter;
+  spaceId: string | undefined;
+  enabled?: boolean;
+}
+
+export function useSpace({ storage, spaceId, enabled = true }: UseSpaceOptions) {
+  return useQuery({
+    queryKey: queryKeys.spaces.detail(spaceId ?? ''),
+    queryFn: async (): Promise<Space | null> => {
+      if (!spaceId) return null;
+      return storage.getSpace(spaceId);
+    },
+    enabled: enabled && !!spaceId,
+    staleTime: 1000 * 60 * 5, // 5 minutes
+  });
+}
+
+export function useSpaceMembers({
+  storage,
+  spaceId,
+  enabled = true,
+}: UseSpaceOptions) {
+  return useQuery({
+    queryKey: queryKeys.spaces.members(spaceId ?? ''),
+    queryFn: async () => {
+      if (!spaceId) return [];
+      return storage.getSpaceMembers(spaceId);
+    },
+    enabled: enabled && !!spaceId,
+    staleTime: 1000 * 60 * 2, // 2 minutes
+  });
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @quorum/shared
+ *
+ * Shared types, hooks, and utilities for Quorum mobile and desktop apps
+ */
+
+// Types
+export * from './types';
+
+// Storage
+export * from './storage';
+
+// API
+export * from './api';
+
+// Hooks
+export * from './hooks';
+
+// Utils
+export * from './utils';
+
+// Crypto (E2E encryption)
+export * from './crypto';
+
+// Signing (Ed448)
+export * from './signing';
+
+// Transport (HTTP, WebSocket)
+export * from './transport';
+
+// Sync (hash-based delta synchronization)
+export * from './sync';

package/src/signing/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Signing module exports
+ */
+
+export type { SigningProvider, SignedMessage } from './types';
+
+export { verifySignedMessage, createSignedMessage } from './types';
+
+// WASM implementation (for desktop/web)
+export { WasmSigningProvider } from './wasm-provider';

package/src/signing/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Signing types and SigningProvider interface
+ *
+ * Platform-agnostic message signing and verification.
+ * Uses Ed448 for all signing operations.
+ */
+
+/**
+ * SigningProvider - Platform-agnostic interface for cryptographic signing
+ *
+ * Implementations:
+ * - WASM (desktop/web): Uses channel-wasm js_sign_ed448/js_verify_ed448
+ * - Native (iOS/Android): Uses uniffi-generated bindings
+ */
+export interface SigningProvider {
+  /**
+   * Sign a message using Ed448
+   * @param privateKey Base64-encoded Ed448 private key (56 bytes)
+   * @param message Base64-encoded message to sign
+   * @returns Base64-encoded signature (114 bytes)
+   */
+  signEd448(privateKey: string, message: string): Promise<string>;
+
+  /**
+   * Verify an Ed448 signature
+   * @param publicKey Base64-encoded Ed448 public key (57 bytes)
+   * @param message Base64-encoded original message
+   * @param signature Base64-encoded signature to verify
+   * @returns true if signature is valid, false otherwise
+   */
+  verifyEd448(publicKey: string, message: string, signature: string): Promise<boolean>;
+}
+
+/**
+ * Signed message structure
+ */
+export interface SignedMessage {
+  /** The message content (may be encrypted) */
+  content: string;
+  /** Base64-encoded Ed448 signature */
+  signature: string;
+  /** Base64-encoded Ed448 public key of signer */
+  publicKey: string;
+  /** Timestamp when signed */
+  timestamp: number;
+}
+
+/**
+ * Verify a signed message structure
+ */
+export async function verifySignedMessage(
+  provider: SigningProvider,
+  message: SignedMessage
+): Promise<boolean> {
+  // Reconstruct the signed payload (content + timestamp)
+  const payload = `${message.content}:${message.timestamp}`;
+  const payloadBase64 = btoa(payload);
+
+  return provider.verifyEd448(message.publicKey, payloadBase64, message.signature);
+}
+
+/**
+ * Create a signed message
+ */
+export async function createSignedMessage(
+  provider: SigningProvider,
+  privateKey: string,
+  publicKey: string,
+  content: string
+): Promise<SignedMessage> {
+  const timestamp = Date.now();
+  const payload = `${content}:${timestamp}`;
+  const payloadBase64 = btoa(payload);
+
+  const signature = await provider.signEd448(privateKey, payloadBase64);
+
+  return {
+    content,
+    signature,
+    publicKey,
+    timestamp,
+  };
+}

package/src/signing/wasm-provider.ts

@@ -0,0 +1,75 @@
+/**
+ * WASM SigningProvider implementation
+ *
+ * Wraps the channel-wasm WASM module to implement the SigningProvider interface.
+ * Used by desktop/web applications.
+ */
+
+import type { SigningProvider } from './types';
+import type { ChannelWasmModule } from '../crypto/wasm-provider';
+
+/**
+ * Parse WASM verification result
+ * Returns true for "true"/"valid", false for "false"/"invalid"
+ */
+function parseVerifyResult(result: string): boolean {
+  const normalized = result.toLowerCase().trim();
+  if (normalized === 'true' || normalized === 'valid') {
+    return true;
+  }
+  if (normalized === 'false' || normalized === 'invalid') {
+    return false;
+  }
+  // Check for error patterns
+  if (
+    result.startsWith('invalid') ||
+    result.startsWith('error') ||
+    result.includes('failed') ||
+    result.includes('Error')
+  ) {
+    throw new Error(result);
+  }
+  // Try to parse as JSON boolean
+  try {
+    return JSON.parse(result) as boolean;
+  } catch {
+    throw new Error(`Unexpected verification result: ${result}`);
+  }
+}
+
+/**
+ * WasmSigningProvider - Implements SigningProvider using channel-wasm
+ */
+export class WasmSigningProvider implements SigningProvider {
+  private wasm: ChannelWasmModule;
+
+  constructor(wasmModule: ChannelWasmModule) {
+    this.wasm = wasmModule;
+  }
+
+  async signEd448(privateKey: string, message: string): Promise<string> {
+    const result = this.wasm.js_sign_ed448(privateKey, message);
+
+    // Check for error patterns
+    if (
+      result.startsWith('invalid') ||
+      result.startsWith('error') ||
+      result.includes('failed') ||
+      result.includes('Error')
+    ) {
+      throw new Error(result);
+    }
+
+    // Remove quotes if present (WASM returns quoted string)
+    if (result.startsWith('"') && result.endsWith('"')) {
+      return result.slice(1, -1);
+    }
+
+    return result;
+  }
+
+  async verifyEd448(publicKey: string, message: string, signature: string): Promise<boolean> {
+    const result = this.wasm.js_verify_ed448(publicKey, message, signature);
+    return parseVerifyResult(result);
+  }
+}

package/src/storage/adapter.ts

@@ -0,0 +1,118 @@
+/**
+ * StorageAdapter interface
+ *
+ * Platform-agnostic storage interface that can be implemented by:
+ * - IndexedDB (desktop/web)
+ * - MMKV (React Native mobile)
+ */
+
+import type { Space, Channel, Message, Conversation, UserConfig, SpaceMember } from '../types';
+import type { MessageDigest, MemberDigest, DeletedMessageTombstone } from '../sync/types';
+
+export interface GetMessagesParams {
+  spaceId: string;
+  channelId: string;
+  cursor?: number;
+  direction?: 'forward' | 'backward';
+  limit?: number;
+}
+
+export interface GetMessagesResult {
+  messages: Message[];
+  nextCursor: number | null;
+  prevCursor: number | null;
+}
+
+export interface StorageAdapter {
+  // Initialization
+  init(): Promise<void>;
+
+  // Spaces
+  getSpaces(): Promise<Space[]>;
+  getSpace(spaceId: string): Promise<Space | null>;
+  saveSpace(space: Space): Promise<void>;
+  deleteSpace(spaceId: string): Promise<void>;
+
+  // Channels (embedded in Space, but may need separate access)
+  getChannels(spaceId: string): Promise<Channel[]>;
+
+  // Messages
+  getMessages(params: GetMessagesParams): Promise<GetMessagesResult>;
+  getMessage(params: {
+    spaceId: string;
+    channelId: string;
+    messageId: string;
+  }): Promise<Message | undefined>;
+  saveMessage(
+    message: Message,
+    lastMessageTimestamp: number,
+    address: string,
+    conversationType: string,
+    icon: string,
+    displayName: string
+  ): Promise<void>;
+  deleteMessage(messageId: string): Promise<void>;
+
+  // Conversations (DMs)
+  getConversations(params: {
+    type: 'direct' | 'group';
+    cursor?: number;
+    limit?: number;
+  }): Promise<{ conversations: Conversation[]; nextCursor: number | null }>;
+  getConversation(conversationId: string): Promise<Conversation | undefined>;
+  saveConversation(conversation: Conversation): Promise<void>;
+  deleteConversation(conversationId: string): Promise<void>;
+
+  // User Config
+  getUserConfig(address: string): Promise<UserConfig | undefined>;
+  saveUserConfig(userConfig: UserConfig): Promise<void>;
+
+  // Space Members
+  getSpaceMembers(spaceId: string): Promise<SpaceMember[]>;
+  getSpaceMember(spaceId: string, address: string): Promise<SpaceMember | undefined>;
+  saveSpaceMember(spaceId: string, member: SpaceMember): Promise<void>;
+
+  // Sync metadata
+  getLastSyncTime(key: string): Promise<number | undefined>;
+  setLastSyncTime(key: string, time: number): Promise<void>;
+
+  // Sync-specific queries (optional - for optimized sync)
+  // If not implemented, SyncService will compute these from full data
+
+  /**
+   * Get message digests for efficient sync comparison.
+   * If not implemented, returns undefined and SyncService computes from messages.
+   */
+  getMessageDigests?(spaceId: string, channelId: string): Promise<MessageDigest[] | undefined>;
+
+  /**
+   * Get messages by IDs for delta sync.
+   * If not implemented, returns undefined and caller fetches individually.
+   */
+  getMessagesByIds?(
+    spaceId: string,
+    channelId: string,
+    ids: string[]
+  ): Promise<Message[] | undefined>;
+
+  /**
+   * Get member digests for efficient sync comparison.
+   * If not implemented, returns undefined and SyncService computes from members.
+   */
+  getMemberDigests?(spaceId: string): Promise<MemberDigest[] | undefined>;
+
+  /**
+   * Get deleted message tombstones for sync.
+   */
+  getTombstones?(spaceId: string, channelId: string): Promise<DeletedMessageTombstone[]>;
+
+  /**
+   * Save deleted message tombstone.
+   */
+  saveTombstone?(tombstone: DeletedMessageTombstone): Promise<void>;
+
+  /**
+   * Clean up old tombstones.
+   */
+  cleanupTombstones?(maxAgeMs: number): Promise<void>;
+}

package/src/storage/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Storage exports
+ */
+
+export type {
+  StorageAdapter,
+  GetMessagesParams,
+  GetMessagesResult,
+} from './adapter';

package/src/sync/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Sync Module
+ *
+ * Hash-based delta synchronization for efficient data transfer.
+ */
+
+// Types
+export type {
+  // Message sync
+  MessageDigest,
+  ReactionDigest,
+  SyncManifest,
+  MessageDelta,
+  ReactionDelta,
+  // Member sync
+  MemberDigest,
+  MemberDelta,
+  // Peer map sync
+  PeerEntry,
+  PeerMapDelta,
+  // Tombstones
+  DeletedMessageTombstone,
+  // Control messages
+  SyncSummary,
+  SyncRequestPayload,
+  SyncInfoPayload,
+  SyncInitiatePayload,
+  SyncManifestPayload,
+  SyncDeltaPayload,
+  // State
+  SyncCandidate,
+  SyncSession,
+  // Union
+  SyncControlPayload,
+} from './types';
+
+// Type guards
+export {
+  isSyncRequest,
+  isSyncInfo,
+  isSyncInitiate,
+  isSyncManifest,
+  isSyncDelta,
+} from './types';
+
+// Utils
+export {
+  // Constants
+  MAX_CHUNK_SIZE,
+  DEFAULT_SYNC_EXPIRY_MS,
+  AGGRESSIVE_SYNC_TIMEOUT_MS,
+  // Hash functions
+  computeHash,
+  computeContentHash,
+  computeReactionHash,
+  computeMemberHash,
+  computeManifestHash,
+  // Digest creation
+  createMessageDigest,
+  createReactionDigest,
+  createManifest,
+  createMemberDigest,
+  // Delta calculation
+  computeMessageDiff,
+  computeReactionDiff,
+  computeMemberDiff,
+  computePeerDiff,
+  // Delta building
+  buildMessageDelta,
+  buildReactionDelta,
+  buildMemberDelta,
+  // Chunking
+  chunkMessages,
+  chunkMembers,
+  // Summary
+  createSyncSummary,
+} from './utils';
+
+export type { MessageDiffResult, ReactionDiffResult, MemberDiffResult, PeerDiffResult } from './utils';
+
+// Service
+export { SyncService } from './service';
+export type { SyncServiceConfig } from './service';