@quilibrium/quorum-shared 2.1.0-1

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@quilibrium/quorum-shared",
+  "version": "2.1.0-1",
+  "description": "Shared types, hooks, and utilities for Quorum mobile and desktop apps",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src --ext .ts,.tsx",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.3.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.62.0",
+    "@types/react": "^18.2.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "react": "^18.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.16"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "quorum",
+    "chat",
+    "shared"
+  ],
+  "license": "MIT"
+}

package/src/api/client.ts

@@ -0,0 +1,86 @@
+/**
+ * QuorumApiClient interface
+ *
+ * Platform-agnostic API client that can be implemented differently
+ * for mobile (fetch) and desktop (Electron IPC or fetch)
+ */
+
+import type { Space, Message, Conversation } from '../types';
+
+export interface SendMessageParams {
+  spaceId: string;
+  channelId: string;
+  text: string;
+  repliesToMessageId?: string;
+}
+
+export interface AddReactionParams {
+  spaceId: string;
+  channelId: string;
+  messageId: string;
+  reaction: string;
+}
+
+export interface RemoveReactionParams {
+  spaceId: string;
+  channelId: string;
+  messageId: string;
+  reaction: string;
+}
+
+export interface EditMessageParams {
+  spaceId: string;
+  channelId: string;
+  messageId: string;
+  text: string;
+}
+
+export interface DeleteMessageParams {
+  spaceId: string;
+  channelId: string;
+  messageId: string;
+}
+
+export interface SendDirectMessageParams {
+  conversationId: string;
+  text: string;
+  repliesToMessageId?: string;
+}
+
+export interface QuorumApiClient {
+  // Spaces
+  fetchSpaces(): Promise<Space[]>;
+  fetchSpace(spaceId: string): Promise<Space>;
+  joinSpace(inviteCode: string): Promise<Space>;
+
+  // Messages
+  fetchMessages(params: {
+    spaceId: string;
+    channelId: string;
+    cursor?: string;
+    limit?: number;
+  }): Promise<{ messages: Message[]; nextPageToken?: string }>;
+
+  sendMessage(params: SendMessageParams): Promise<Message>;
+  editMessage(params: EditMessageParams): Promise<Message>;
+  deleteMessage(params: DeleteMessageParams): Promise<void>;
+
+  // Reactions
+  addReaction(params: AddReactionParams): Promise<void>;
+  removeReaction(params: RemoveReactionParams): Promise<void>;
+
+  // Conversations
+  fetchConversations(): Promise<Conversation[]>;
+  createConversation(params: { address: string }): Promise<Conversation>;
+  sendDirectMessage(params: SendDirectMessageParams): Promise<Message>;
+  fetchDirectMessages(params: {
+    conversationId: string;
+    cursor?: string;
+    limit?: number;
+  }): Promise<{ messages: Message[]; nextPageToken?: string }>;
+
+  // Pinning
+  pinMessage(params: { spaceId: string; channelId: string; messageId: string }): Promise<void>;
+  unpinMessage(params: { spaceId: string; channelId: string; messageId: string }): Promise<void>;
+}
+

package/src/api/endpoints.ts

@@ -0,0 +1,87 @@
+/**
+ * API endpoint definitions
+ */
+
+/** Base API configuration */
+export interface ApiConfig {
+  baseUrl: string;
+  timeout?: number;
+}
+
+/** API endpoint builders */
+export const endpoints = {
+  // Spaces
+  spaces: {
+    list: () => '/spaces',
+    detail: (spaceId: string) => `/spaces/${spaceId}`,
+    members: (spaceId: string) => `/spaces/${spaceId}/members`,
+    join: (spaceId: string) => `/spaces/${spaceId}/join`,
+    leave: (spaceId: string) => `/spaces/${spaceId}/leave`,
+  },
+
+  // Channels
+  channels: {
+    list: (spaceId: string) => `/spaces/${spaceId}/channels`,
+    detail: (spaceId: string, channelId: string) =>
+      `/spaces/${spaceId}/channels/${channelId}`,
+  },
+
+  // Messages
+  messages: {
+    list: (spaceId: string, channelId: string) =>
+      `/spaces/${spaceId}/channels/${channelId}/messages`,
+    detail: (spaceId: string, channelId: string, messageId: string) =>
+      `/spaces/${spaceId}/channels/${channelId}/messages/${messageId}`,
+    send: (spaceId: string, channelId: string) =>
+      `/spaces/${spaceId}/channels/${channelId}/messages`,
+    react: (spaceId: string, channelId: string, messageId: string) =>
+      `/spaces/${spaceId}/channels/${channelId}/messages/${messageId}/reactions`,
+    pin: (spaceId: string, channelId: string, messageId: string) =>
+      `/spaces/${spaceId}/channels/${channelId}/messages/${messageId}/pin`,
+  },
+
+  // Conversations (DMs)
+  conversations: {
+    list: () => '/conversations',
+    detail: (conversationId: string) => `/conversations/${conversationId}`,
+    messages: (conversationId: string) => `/conversations/${conversationId}/messages`,
+  },
+
+  // User
+  user: {
+    config: () => '/user/config',
+    profile: () => '/user/profile',
+    notifications: () => '/user/notifications',
+  },
+
+  // Search
+  search: {
+    messages: (spaceId: string) => `/spaces/${spaceId}/search/messages`,
+    members: (spaceId: string) => `/spaces/${spaceId}/search/members`,
+  },
+} as const;
+
+/** HTTP methods */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/** Request options */
+export interface RequestOptions {
+  method?: HttpMethod;
+  headers?: Record<string, string>;
+  body?: unknown;
+  timeout?: number;
+  signal?: AbortSignal;
+}
+
+/** Pagination parameters */
+export interface PaginationParams {
+  cursor?: string;
+  limit?: number;
+}
+
+/** Message list parameters */
+export interface MessageListParams extends PaginationParams {
+  before?: string;
+  after?: string;
+  around?: string;
+}

package/src/api/errors.ts

@@ -0,0 +1,179 @@
+/**
+ * API error classes
+ */
+
+/** API error codes */
+export enum ApiErrorCode {
+  // Network errors
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  TIMEOUT = 'TIMEOUT',
+
+  // Auth errors
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+  TOKEN_EXPIRED = 'TOKEN_EXPIRED',
+
+  // Validation errors
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  BAD_REQUEST = 'BAD_REQUEST',
+
+  // Resource errors
+  NOT_FOUND = 'NOT_FOUND',
+  CONFLICT = 'CONFLICT',
+
+  // Rate limiting
+  RATE_LIMITED = 'RATE_LIMITED',
+
+  // Server errors
+  SERVER_ERROR = 'SERVER_ERROR',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+
+  // Unknown
+  UNKNOWN = 'UNKNOWN',
+}
+
+/** API error details */
+export interface ApiErrorDetails {
+  code: ApiErrorCode;
+  message: string;
+  status?: number;
+  field?: string;
+  retryAfter?: number;
+  originalError?: Error;
+}
+
+/**
+ * Custom API error class
+ */
+export class ApiError extends Error {
+  readonly code: ApiErrorCode;
+  readonly status?: number;
+  readonly field?: string;
+  readonly retryAfter?: number;
+  readonly originalError?: Error;
+
+  constructor(details: ApiErrorDetails) {
+    super(details.message);
+    this.name = 'ApiError';
+    this.code = details.code;
+    this.status = details.status;
+    this.field = details.field;
+    this.retryAfter = details.retryAfter;
+    this.originalError = details.originalError;
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ApiError);
+    }
+  }
+
+  /** Check if error is retryable */
+  get isRetryable(): boolean {
+    return [
+      ApiErrorCode.NETWORK_ERROR,
+      ApiErrorCode.TIMEOUT,
+      ApiErrorCode.RATE_LIMITED,
+      ApiErrorCode.SERVER_ERROR,
+      ApiErrorCode.SERVICE_UNAVAILABLE,
+    ].includes(this.code);
+  }
+
+  /** Check if error requires re-authentication */
+  get requiresAuth(): boolean {
+    return [
+      ApiErrorCode.UNAUTHORIZED,
+      ApiErrorCode.TOKEN_EXPIRED,
+    ].includes(this.code);
+  }
+
+  /** Convert to JSON-serializable object */
+  toJSON(): ApiErrorDetails {
+    return {
+      code: this.code,
+      message: this.message,
+      status: this.status,
+      field: this.field,
+      retryAfter: this.retryAfter,
+    };
+  }
+}
+
+/**
+ * Create ApiError from HTTP response
+ */
+export function createApiError(
+  status: number,
+  message?: string,
+  field?: string
+): ApiError {
+  let code: ApiErrorCode;
+  let defaultMessage: string;
+
+  switch (status) {
+    case 400:
+      code = ApiErrorCode.BAD_REQUEST;
+      defaultMessage = 'Invalid request';
+      break;
+    case 401:
+      code = ApiErrorCode.UNAUTHORIZED;
+      defaultMessage = 'Authentication required';
+      break;
+    case 403:
+      code = ApiErrorCode.FORBIDDEN;
+      defaultMessage = 'Access denied';
+      break;
+    case 404:
+      code = ApiErrorCode.NOT_FOUND;
+      defaultMessage = 'Resource not found';
+      break;
+    case 409:
+      code = ApiErrorCode.CONFLICT;
+      defaultMessage = 'Resource conflict';
+      break;
+    case 422:
+      code = ApiErrorCode.VALIDATION_ERROR;
+      defaultMessage = 'Validation failed';
+      break;
+    case 429:
+      code = ApiErrorCode.RATE_LIMITED;
+      defaultMessage = 'Rate limit exceeded';
+      break;
+    case 500:
+      code = ApiErrorCode.SERVER_ERROR;
+      defaultMessage = 'Server error';
+      break;
+    case 503:
+      code = ApiErrorCode.SERVICE_UNAVAILABLE;
+      defaultMessage = 'Service unavailable';
+      break;
+    default:
+      code = ApiErrorCode.UNKNOWN;
+      defaultMessage = 'An unexpected error occurred';
+  }
+
+  return new ApiError({
+    code,
+    message: message || defaultMessage,
+    status,
+    field,
+  });
+}
+
+/**
+ * Create ApiError from network error
+ */
+export function createNetworkError(error: Error): ApiError {
+  if (error.name === 'AbortError') {
+    return new ApiError({
+      code: ApiErrorCode.TIMEOUT,
+      message: 'Request timed out',
+      originalError: error,
+    });
+  }
+
+  return new ApiError({
+    code: ApiErrorCode.NETWORK_ERROR,
+    message: 'Network error',
+    originalError: error,
+  });
+}

package/src/api/index.ts

@@ -0,0 +1,35 @@
+/**
+ * API exports
+ */
+
+// Client interface and types
+export type {
+  QuorumApiClient,
+  SendMessageParams,
+  SendDirectMessageParams,
+  AddReactionParams,
+  RemoveReactionParams,
+  EditMessageParams,
+  DeleteMessageParams,
+} from './client';
+
+// Errors
+export {
+  ApiError,
+  ApiErrorCode,
+  createApiError,
+  createNetworkError,
+} from './errors';
+export type { ApiErrorDetails } from './errors';
+
+// Endpoints
+export {
+  endpoints,
+} from './endpoints';
+export type {
+  ApiConfig,
+  HttpMethod,
+  RequestOptions,
+  PaginationParams,
+  MessageListParams,
+} from './endpoints';

package/src/crypto/encryption-state.ts

@@ -0,0 +1,249 @@
+/**
+ * Encryption State Types and Storage Interface
+ *
+ * Platform-agnostic types for managing Double Ratchet encryption states.
+ * The actual storage implementation is platform-specific (MMKV for mobile, IndexedDB for desktop).
+ */
+
+// ============ Device & Recipient Types ============
+
+/**
+ * DeviceKeys - Device's cryptographic keypairs for E2E encryption
+ * Used for X3DH key exchange and inbox message unsealing
+ */
+export interface DeviceKeys {
+  /** X448 identity key for X3DH - private key */
+  identityPrivateKey: number[];
+  /** X448 identity key for X3DH - public key */
+  identityPublicKey: number[];
+  /** X448 signed pre-key for X3DH - private key */
+  preKeyPrivateKey: number[];
+  /** X448 signed pre-key for X3DH - public key */
+  preKeyPublicKey: number[];
+  /** X448 inbox encryption key for unsealing - private key */
+  inboxEncryptionPrivateKey: number[];
+  /** X448 inbox encryption key for unsealing - public key */
+  inboxEncryptionPublicKey: number[];
+}
+
+/**
+ * RecipientInfo - Recipient's public keys needed for encryption
+ * Used to establish X3DH session and seal messages
+ */
+export interface RecipientInfo {
+  /** Recipient's address */
+  address: string;
+  /** X448 identity public key for X3DH */
+  identityKey: number[];
+  /** X448 signed pre-key for X3DH */
+  signedPreKey: number[];
+  /** Recipient's inbox address */
+  inboxAddress: string;
+  /** X448 public key for sealing envelopes to recipient's inbox */
+  inboxEncryptionKey?: number[];
+}
+
+/**
+ * EncryptedEnvelope - Result of encrypting a message
+ */
+export interface EncryptedEnvelope {
+  /** The encrypted Double Ratchet envelope */
+  envelope: string;
+  /** Recipient's inbox address */
+  inboxAddress: string;
+  /** Ephemeral public key (only set for first message in new session) */
+  ephemeralPublicKey?: number[];
+  /** Ephemeral private key (only set for first message - needed for sealing) */
+  ephemeralPrivateKey?: number[];
+}
+
+// ============ Storage Provider Interface ============
+
+/**
+ * KeyValueStorageProvider - Platform-agnostic key-value storage interface
+ *
+ * Implementations:
+ * - MMKV (React Native)
+ * - IndexedDB (Desktop/Web)
+ * - AsyncStorage (React Native fallback)
+ */
+export interface KeyValueStorageProvider {
+  /**
+   * Get a string value by key
+   * @returns The value or null if not found
+   */
+  getString(key: string): string | null;
+
+  /**
+   * Set a string value
+   */
+  set(key: string, value: string): void;
+
+  /**
+   * Remove a key
+   */
+  remove(key: string): void;
+
+  /**
+   * Get all keys in storage
+   */
+  getAllKeys(): string[];
+
+  /**
+   * Clear all data from storage
+   */
+  clearAll(): void;
+}
+
+// ============ Inbox Types ============
+
+/**
+ * SendingInbox - Recipient's inbox info needed for sealing messages
+ * Matches desktop SDK's SendingInbox type
+ */
+export interface SendingInbox {
+  /** Recipient's inbox address where we send to */
+  inbox_address: string;
+  /** Recipient's X448 public key for sealing (hex) */
+  inbox_encryption_key: string;
+  /** Recipient's Ed448 public key (hex) - empty until confirmed */
+  inbox_public_key: string;
+  /** Always empty - we don't have their private key */
+  inbox_private_key: string;
+}
+
+/**
+ * ReceivingInbox - Our inbox info for receiving replies
+ * Simplified version (full keypair stored separately in ConversationInboxKeypair)
+ */
+export interface ReceivingInbox {
+  /** Our inbox address where we receive replies */
+  inbox_address: string;
+}
+
+// ============ Encryption State ============
+
+/**
+ * EncryptionState - Double Ratchet state for a conversation+inbox pair
+ * Matches desktop's DoubleRatchetStateAndInboxKeys structure
+ */
+export interface EncryptionState {
+  /** JSON-serialized ratchet state */
+  state: string;
+  /** When state was created/updated */
+  timestamp: number;
+  /** Conversation identifier */
+  conversationId: string;
+  /** Associated inbox ID (our receiving inbox) */
+  inboxId: string;
+  /** Whether we've sent an accept message */
+  sentAccept?: boolean;
+  /** Recipient's inbox info for sealing messages */
+  sendingInbox?: SendingInbox;
+  /** Session tag (usually our inbox address) */
+  tag?: string;
+  /**
+   * X3DH ephemeral public key (hex) used for session establishment.
+   * MUST be reused for all init envelopes until session is confirmed.
+   * This ensures the receiver can derive the same session key via X3DH.
+   */
+  x3dhEphemeralPublicKey?: string;
+  /**
+   * X3DH ephemeral private key (hex) used for session establishment.
+   * MUST be reused for sealing init envelopes until session is confirmed.
+   */
+  x3dhEphemeralPrivateKey?: string;
+}
+
+// ============ Inbox Mapping ============
+
+/**
+ * InboxMapping - Maps inbox address to conversation
+ */
+export interface InboxMapping {
+  inboxId: string;
+  conversationId: string;
+}
+
+/**
+ * LatestState - Tracks the most recent state for a conversation
+ */
+export interface LatestState {
+  conversationId: string;
+  inboxId: string;
+  timestamp: number;
+}
+
+// ============ Conversation Inbox Keypair ============
+
+/**
+ * ConversationInboxKeypair - Per-conversation inbox keypair for receiving replies
+ * Mirrors desktop's InboxKeyset structure with both Ed448 and X448 keys
+ */
+export interface ConversationInboxKeypair {
+  conversationId: string;
+  inboxAddress: string;
+  /** X448 encryption public key (for sealing/unsealing messages) */
+  encryptionPublicKey: number[];
+  /** X448 encryption private key */
+  encryptionPrivateKey: number[];
+  /** Ed448 signing public key (for signing/verifying inbox messages) */
+  signingPublicKey?: number[];
+  /** Ed448 signing private key */
+  signingPrivateKey?: number[];
+}
+
+// ============ Storage Key Prefixes ============
+
+/**
+ * Storage key prefixes for encryption state data
+ */
+export const ENCRYPTION_STORAGE_KEYS = {
+  /** enc_state:{conversationId}:{inboxId} */
+  ENCRYPTION_STATE: 'enc_state:',
+  /** inbox_map:{inboxId} */
+  INBOX_MAPPING: 'inbox_map:',
+  /** latest:{conversationId} */
+  LATEST_STATE: 'latest:',
+  /** conv_inboxes:{conversationId} -> inboxId[] */
+  CONVERSATION_INBOXES: 'conv_inboxes:',
+  /** conv_inbox_key:{conversationId} -> ConversationInboxKeypair */
+  CONVERSATION_INBOX_KEY: 'conv_inbox_key:',
+} as const;
+
+// ============ Encryption State Storage Interface ============
+
+/**
+ * EncryptionStateStorageInterface - Interface for managing encryption states
+ *
+ * This interface defines the contract for encryption state storage.
+ * Implementations use platform-specific storage backends.
+ */
+export interface EncryptionStateStorageInterface {
+  // Encryption States
+  getEncryptionState(conversationId: string, inboxId: string): EncryptionState | null;
+  getEncryptionStates(conversationId: string): EncryptionState[];
+  saveEncryptionState(state: EncryptionState, updateLatest?: boolean): void;
+  deleteEncryptionState(conversationId: string, inboxId: string): void;
+  deleteAllEncryptionStates(conversationId: string): void;
+
+  // Inbox Mapping
+  getInboxMapping(inboxId: string): InboxMapping | null;
+  saveInboxMapping(inboxId: string, conversationId: string): void;
+  deleteInboxMapping(inboxId: string): void;
+
+  // Latest State
+  getLatestState(conversationId: string): LatestState | null;
+
+  // Conversation Inbox Keypairs
+  saveConversationInboxKeypair(keypair: ConversationInboxKeypair): void;
+  getConversationInboxKeypair(conversationId: string): ConversationInboxKeypair | null;
+  deleteConversationInboxKeypair(conversationId: string): void;
+  getConversationInboxKeypairByAddress(inboxAddress: string): ConversationInboxKeypair | null;
+  getAllConversationInboxAddresses(): string[];
+
+  // Utilities
+  clearAll(): void;
+  hasEncryptionState(conversationId: string): boolean;
+  getStatesByInboxId(inboxId: string): Array<{ conversationId: string; state: EncryptionState }>;
+}