@meshwhisper/sdk 0.1.0

package/src/permissions/index.ts

@@ -0,0 +1,405 @@
+// ============================================================
+// MeshWhisper SDK — Contact Permissions Module
+// Endpoint-side permission enforcement for P2P contact initiation.
+// ============================================================
+
+import type { PermissionModel } from '../types';
+
+// --- Interfaces ---
+
+export interface ContactContext {
+  senderId: string;
+  senderPublicKey: Uint8Array;
+  timestamp: number;
+  introductionBy?: string;
+  transactionEvent?: string;
+}
+
+export interface PermissionOptions {
+  customHandler?: (
+    senderId: string,
+    context: ContactContext,
+  ) => boolean | Promise<boolean>;
+  transactionVerifier?: (
+    senderId: string,
+    event: string,
+  ) => boolean | Promise<boolean>;
+  allowList?: Set<string>;
+  blockList?: Set<string>;
+}
+
+export interface ContactRequest {
+  id: string;
+  fromPeerId: string;
+  toPeerId: string;
+  timestamp: number;
+  status: 'pending' | 'accepted' | 'rejected';
+}
+
+export interface IntroductionRequest {
+  id: string;
+  fromPeerId: string;
+  toPeerId: string;
+  introducerPeerId: string;
+  timestamp: number;
+  status: 'pending' | 'introduced' | 'accepted' | 'rejected';
+}
+
+// --- Helpers ---
+
+function generateId(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+// --- PermissionManager ---
+
+export class PermissionManager {
+  private model: PermissionModel;
+  private readonly customHandler?: (
+    senderId: string,
+    context: ContactContext,
+  ) => boolean | Promise<boolean>;
+  private readonly transactionVerifier?: (
+    senderId: string,
+    event: string,
+  ) => boolean | Promise<boolean>;
+
+  private readonly contacts: Set<string> = new Set();
+  private readonly blocked: Set<string> = new Set();
+  private readonly allowed: Set<string> = new Set();
+
+  /** Peers who have sent us a contact request (mutual model). */
+  private readonly inboundRequests: Map<string, ContactRequest> = new Map();
+  /** Peers we have sent a contact request to (mutual model). */
+  private readonly outboundRequests: Map<string, ContactRequest> = new Map();
+
+  /** Introduction requests keyed by request id. */
+  private readonly introductionRequests: Map<string, IntroductionRequest> =
+    new Map();
+
+  /** Peers whose mutual contact has been confirmed (both sides accepted). */
+  private readonly mutualConfirmed: Set<string> = new Set();
+
+  /** Peers introduced to us via a trusted intermediary. */
+  private readonly introducedPeers: Set<string> = new Set();
+
+  constructor(model: PermissionModel, options?: PermissionOptions) {
+    this.model = model;
+
+    if (options?.customHandler) {
+      this.customHandler = options.customHandler;
+    }
+    if (options?.transactionVerifier) {
+      this.transactionVerifier = options.transactionVerifier;
+    }
+    if (options?.allowList) {
+      for (const id of options.allowList) {
+        this.allowed.add(id);
+      }
+    }
+    if (options?.blockList) {
+      for (const id of options.blockList) {
+        this.blocked.add(id);
+      }
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Model switching
+  // ------------------------------------------------------------------
+
+  setModel(model: PermissionModel): void {
+    this.model = model;
+  }
+
+  getModel(): PermissionModel {
+    return this.model;
+  }
+
+  // ------------------------------------------------------------------
+  // Contact management
+  // ------------------------------------------------------------------
+
+  addContact(peerId: string): void {
+    this.contacts.add(peerId);
+  }
+
+  removeContact(peerId: string): void {
+    this.contacts.delete(peerId);
+    this.mutualConfirmed.delete(peerId);
+  }
+
+  isContact(peerId: string): boolean {
+    return this.contacts.has(peerId);
+  }
+
+  getContacts(): string[] {
+    return Array.from(this.contacts);
+  }
+
+  loadContacts(contacts: string[]): void {
+    for (const id of contacts) this.contacts.add(id);
+  }
+
+  blockPeer(peerId: string): void {
+    this.blocked.add(peerId);
+  }
+
+  unblockPeer(peerId: string): void {
+    this.blocked.delete(peerId);
+  }
+
+  isBlocked(peerId: string): boolean {
+    return this.blocked.has(peerId);
+  }
+
+  // ------------------------------------------------------------------
+  // Permission checks
+  // ------------------------------------------------------------------
+
+  /**
+   * Main inbound permission check.
+   * Order: blockList -> allowList -> model-specific logic.
+   */
+  async canReceiveFrom(
+    senderId: string,
+    context: ContactContext,
+  ): Promise<boolean> {
+    // Always deny blocked peers.
+    if (this.blocked.has(senderId)) {
+      return false;
+    }
+
+    // Always allow explicitly allowed peers.
+    if (this.allowed.has(senderId)) {
+      return true;
+    }
+
+    // Existing contacts are always permitted regardless of model.
+    if (this.contacts.has(senderId)) {
+      return true;
+    }
+
+    switch (this.model) {
+      case 'open':
+        return true;
+
+      case 'mutual':
+        return this.mutualConfirmed.has(senderId);
+
+      case 'introduction':
+        return this.introducedPeers.has(senderId) || this.checkIntroduction(senderId, context);
+
+      case 'transactional':
+        return this.checkTransaction(senderId, context);
+
+      case 'custom':
+        return this.checkCustom(senderId, context);
+
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Outbound permission check — can we send to this recipient?
+   * Primarily relevant for the mutual model where both sides
+   * need to have each other as contacts.
+   */
+  async canSendTo(recipientId: string): Promise<boolean> {
+    // Never send to blocked peers.
+    if (this.blocked.has(recipientId)) {
+      return false;
+    }
+
+    // Always allowed peers.
+    if (this.allowed.has(recipientId)) {
+      return true;
+    }
+
+    switch (this.model) {
+      case 'open':
+        return true;
+
+      case 'mutual':
+        // Can only send if mutual contact has been confirmed or they are
+        // already a known contact.
+        return this.contacts.has(recipientId) || this.mutualConfirmed.has(recipientId);
+
+      case 'introduction':
+        return (
+          this.contacts.has(recipientId) || this.introducedPeers.has(recipientId)
+        );
+
+      case 'transactional':
+        // For outbound in transactional model, allow if they are a contact.
+        return this.contacts.has(recipientId);
+
+      case 'custom':
+        // Custom model defers to the handler for inbound only;
+        // outbound is permitted to any non-blocked peer.
+        return true;
+
+      default:
+        return false;
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Mutual model logic
+  // ------------------------------------------------------------------
+
+  /**
+   * Create a contact request to send to a peer (mutual model).
+   * The caller is responsible for transmitting the request over the wire.
+   */
+  requestMutualContact(peerId: string): ContactRequest {
+    const request: ContactRequest = {
+      id: generateId(),
+      fromPeerId: '', // Will be filled by the caller with own peer ID
+      toPeerId: peerId,
+      timestamp: Date.now(),
+      status: 'pending',
+    };
+    this.outboundRequests.set(peerId, request);
+    return request;
+  }
+
+  /**
+   * Handle an inbound contact request from a peer.
+   * Returns true if the request is accepted (i.e. we already have an
+   * outbound request to that peer, achieving mutual consent), false
+   * if the request is stored as pending.
+   */
+  handleContactRequest(request: ContactRequest): boolean {
+    if (this.blocked.has(request.fromPeerId)) {
+      request.status = 'rejected';
+      return false;
+    }
+
+    this.inboundRequests.set(request.fromPeerId, request);
+
+    // If we already sent a request to this peer, auto-confirm mutual contact.
+    if (this.outboundRequests.has(request.fromPeerId)) {
+      request.status = 'accepted';
+      const outbound = this.outboundRequests.get(request.fromPeerId)!;
+      outbound.status = 'accepted';
+      this.confirmMutualContact(request.fromPeerId);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Explicitly confirm mutual contact with a peer.
+   * Adds the peer to contacts and the mutualConfirmed set.
+   */
+  confirmMutualContact(peerId: string): void {
+    this.mutualConfirmed.add(peerId);
+    this.contacts.add(peerId);
+  }
+
+  // ------------------------------------------------------------------
+  // Introduction model logic
+  // ------------------------------------------------------------------
+
+  /**
+   * Request an introduction to a target peer through a mutual contact.
+   * The caller is responsible for transmitting the request to the introducer.
+   */
+  requestIntroduction(
+    targetPeerId: string,
+    introducerPeerId: string,
+  ): IntroductionRequest {
+    const request: IntroductionRequest = {
+      id: generateId(),
+      fromPeerId: '', // Will be filled by the caller with own peer ID
+      toPeerId: targetPeerId,
+      introducerPeerId,
+      timestamp: Date.now(),
+      status: 'pending',
+    };
+    this.introductionRequests.set(request.id, request);
+    return request;
+  }
+
+  /**
+   * Handle an introduction request as the intermediary.
+   * Returns true if the introducer is a known contact of ours (trusted),
+   * false otherwise (the intermediary should only broker introductions
+   * between their own contacts).
+   */
+  handleIntroductionRequest(request: IntroductionRequest): boolean {
+    if (this.blocked.has(request.fromPeerId)) {
+      request.status = 'rejected';
+      return false;
+    }
+
+    // The intermediary should know both parties as contacts.
+    const knowsSender = this.contacts.has(request.fromPeerId);
+    const knowsTarget = this.contacts.has(request.toPeerId);
+
+    if (knowsSender && knowsTarget) {
+      request.status = 'introduced';
+      this.introductionRequests.set(request.id, request);
+      return true;
+    }
+
+    request.status = 'rejected';
+    this.introductionRequests.set(request.id, request);
+    return false;
+  }
+
+  /**
+   * Confirm an introduction — called on the receiving end once the
+   * introduction has been brokered by the intermediary.
+   */
+  confirmIntroduction(request: IntroductionRequest): void {
+    request.status = 'accepted';
+    this.introductionRequests.set(request.id, request);
+    this.introducedPeers.add(request.fromPeerId);
+    this.contacts.add(request.fromPeerId);
+  }
+
+  // ------------------------------------------------------------------
+  // Private model-specific checks
+  // ------------------------------------------------------------------
+
+  private checkIntroduction(
+    senderId: string,
+    context: ContactContext,
+  ): boolean {
+    // If the context carries a valid introduction reference, check it.
+    if (context.introductionBy) {
+      // The introducer must be one of our contacts.
+      return this.contacts.has(context.introductionBy);
+    }
+    return false;
+  }
+
+  private async checkTransaction(
+    senderId: string,
+    context: ContactContext,
+  ): Promise<boolean> {
+    if (!this.transactionVerifier || !context.transactionEvent) {
+      return false;
+    }
+    return this.transactionVerifier(senderId, context.transactionEvent);
+  }
+
+  private async checkCustom(
+    senderId: string,
+    context: ContactContext,
+  ): Promise<boolean> {
+    if (!this.customHandler) {
+      // No custom handler configured — deny by default for safety.
+      return false;
+    }
+    return this.customHandler(senderId, context);
+  }
+}

package/src/persistence/idb-storage.ts

@@ -0,0 +1,83 @@
+// ============================================================
+// MeshWhisper SDK — IndexedDB Storage Backend
+// Implements StorageBackend for browsers and PWAs using the
+// native IndexedDB API. No external dependencies.
+// ============================================================
+
+import type { StorageBackend } from './types.js';
+
+const DB_NAME = 'meshwhisper';
+const STORE_NAME = 'kv';
+const DB_VERSION = 1;
+
+function openDB(namespace: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(`${DB_NAME}:${namespace}`, DB_VERSION);
+    req.onupgradeneeded = () => {
+      req.result.createObjectStore(STORE_NAME);
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function request<T>(req: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+/**
+ * IndexedDB-backed storage for MeshWhisper. Use this in browsers and PWAs.
+ *
+ * ```ts
+ * import { IDBStorage } from '@meshwhisper/sdk/browser';
+ *
+ * const mw = await MeshWhisper.init({
+ *   namespace: 'com.example.app',
+ *   storage: new IDBStorage('com.example.app'),
+ * });
+ * ```
+ *
+ * When `MeshWhisper.init()` is called in a browser without an explicit
+ * `storage` option, an `IDBStorage` is created automatically.
+ */
+export class IDBStorage implements StorageBackend {
+  private dbPromise: Promise<IDBDatabase> | null = null;
+
+  constructor(private readonly namespace: string = 'default') {}
+
+  private getDB(): Promise<IDBDatabase> {
+    if (!this.dbPromise) {
+      this.dbPromise = openDB(this.namespace);
+    }
+    return this.dbPromise;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const db = await this.getDB();
+    const tx = db.transaction(STORE_NAME, 'readonly');
+    const val = await request<string | undefined>(tx.objectStore(STORE_NAME).get(key));
+    return val ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const db = await this.getDB();
+    const tx = db.transaction(STORE_NAME, 'readwrite');
+    await request(tx.objectStore(STORE_NAME).put(value, key));
+  }
+
+  async delete(key: string): Promise<void> {
+    const db = await this.getDB();
+    const tx = db.transaction(STORE_NAME, 'readwrite');
+    await request(tx.objectStore(STORE_NAME).delete(key));
+  }
+
+  async keys(prefix: string): Promise<string[]> {
+    const db = await this.getDB();
+    const tx = db.transaction(STORE_NAME, 'readonly');
+    const allKeys = await request<IDBValidKey[]>(tx.objectStore(STORE_NAME).getAllKeys());
+    return (allKeys as string[]).filter((k) => k.startsWith(prefix));
+  }
+}

package/src/persistence/index.ts

@@ -0,0 +1,3 @@
+export type { StorageBackend, StoredMessage } from './types.js';
+export { NodeStorage } from './node-storage.js';
+export { serializeRatchetState, deserializeRatchetState } from './serialization.js';

package/src/persistence/node-storage.ts

@@ -0,0 +1,96 @@
+// ============================================================
+// MeshWhisper SDK — Node.js StorageBackend
+// Filesystem-based persistence using one file per key.
+// Files are written with mode 0600 (owner read/write only).
+// ============================================================
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { StorageBackend } from './types.js';
+
+/**
+ * Node.js StorageBackend backed by the local filesystem.
+ *
+ * Usage:
+ * ```ts
+ * import { MeshWhisper } from '@meshwhisper/sdk';
+ * import { NodeStorage } from '@meshwhisper/sdk/persistence/node';
+ *
+ * const mw = await MeshWhisper.init({
+ *   namespace: 'com.example.myapp',
+ *   storage: new NodeStorage('./data/meshwhisper'),
+ * });
+ * ```
+ *
+ * Data layout under `dataDir/`:
+ *   identity          — hex-encoded Ed25519 private key
+ *   sessions/<id>     — serialized RatchetState (JSON)
+ *   peers/<id>        — hex-encoded X25519 public key
+ *   contacts          — JSON array of peer ID strings
+ *   messages/<id>     — JSON array of StoredMessage
+ *   seen_ids          — JSON array of { id, ts } for deduplication
+ */
+export class NodeStorage implements StorageBackend {
+  private readonly root: string;
+
+  constructor(dataDir: string) {
+    this.root = path.resolve(dataDir);
+    fs.mkdirSync(this.root, { recursive: true });
+  }
+
+  private resolve(key: string): string {
+    // Sanitize: only allow alphanumeric, underscore, hyphen, forward slash, dot
+    const safe = key.replace(/[^a-zA-Z0-9/_.-]/g, '_');
+    const abs = path.join(this.root, safe);
+    // Guard against path traversal
+    if (!abs.startsWith(this.root + path.sep) && abs !== this.root) {
+      throw new Error(`Storage key escapes data directory: ${key}`);
+    }
+    return abs;
+  }
+
+  async get(key: string): Promise<string | null> {
+    try {
+      return fs.readFileSync(this.resolve(key), 'utf-8');
+    } catch {
+      return null;
+    }
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const filePath = this.resolve(key);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    // Write atomically: write to a temp file, then rename
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, value, { encoding: 'utf-8', mode: 0o600 });
+    fs.renameSync(tmp, filePath);
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      fs.unlinkSync(this.resolve(key));
+    } catch {
+      // File doesn't exist — fine
+    }
+  }
+
+  async keys(prefix: string): Promise<string[]> {
+    // Walk the directory corresponding to the prefix
+    const prefixPath = this.resolve(prefix);
+    // The prefix may itself be a directory (e.g. "sessions/") or a path fragment
+    const dir = prefix.endsWith('/') ? prefixPath : path.dirname(prefixPath);
+    const base = prefix.endsWith('/') ? '' : path.basename(prefixPath);
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      return entries
+        .filter((e) => e.isFile() && e.name.startsWith(base))
+        .map((e) => {
+          const rel = path.relative(this.root, path.join(dir, e.name));
+          return rel.replace(/\\/g, '/'); // normalise on Windows
+        });
+    } catch {
+      return [];
+    }
+  }
+}

package/src/persistence/serialization.ts

@@ -0,0 +1,75 @@
+// ============================================================
+// MeshWhisper SDK — RatchetState serialization
+// Converts between the in-memory RatchetState and a JSON string
+// suitable for storage. All Uint8Array fields are hex-encoded.
+// ============================================================
+
+import type { RatchetState } from '../ratchet/index.js';
+
+// ---- Helpers ----
+
+function toHex(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('hex');
+}
+
+function fromHex(hex: string): Uint8Array {
+  return new Uint8Array(Buffer.from(hex, 'hex'));
+}
+
+// ---- Serialized shape ----
+
+interface SerializedRatchetState {
+  v: 1;
+  dhSendingPriv: string;
+  dhSendingPub: string;
+  dhReceiving: string | null;
+  rootKey: string;
+  sendingChainKey: string | null;
+  receivingChainKey: string | null;
+  sendMessageNumber: number;
+  receiveMessageNumber: number;
+  previousSendingChainLength: number;
+  skippedMessageKeys: Record<string, string>;
+}
+
+// ---- Public API ----
+
+export function serializeRatchetState(state: RatchetState): string {
+  const obj: SerializedRatchetState = {
+    v: 1,
+    dhSendingPriv: toHex(state.dhSending.privateKey),
+    dhSendingPub: toHex(state.dhSending.publicKey),
+    dhReceiving: state.dhReceiving ? toHex(state.dhReceiving) : null,
+    rootKey: toHex(state.rootKey),
+    sendingChainKey: state.sendingChainKey ? toHex(state.sendingChainKey) : null,
+    receivingChainKey: state.receivingChainKey ? toHex(state.receivingChainKey) : null,
+    sendMessageNumber: state.sendMessageNumber,
+    receiveMessageNumber: state.receiveMessageNumber,
+    previousSendingChainLength: state.previousSendingChainLength,
+    skippedMessageKeys: Object.fromEntries(
+      [...state.skippedMessageKeys.entries()].map(([k, v]) => [k, toHex(v)]),
+    ),
+  };
+  return JSON.stringify(obj);
+}
+
+export function deserializeRatchetState(json: string): RatchetState {
+  const obj = JSON.parse(json) as SerializedRatchetState;
+  if (obj.v !== 1) throw new Error(`Unknown RatchetState version: ${obj.v}`);
+  return {
+    dhSending: {
+      privateKey: fromHex(obj.dhSendingPriv),
+      publicKey: fromHex(obj.dhSendingPub),
+    },
+    dhReceiving: obj.dhReceiving ? fromHex(obj.dhReceiving) : null,
+    rootKey: fromHex(obj.rootKey),
+    sendingChainKey: obj.sendingChainKey ? fromHex(obj.sendingChainKey) : null,
+    receivingChainKey: obj.receivingChainKey ? fromHex(obj.receivingChainKey) : null,
+    sendMessageNumber: obj.sendMessageNumber,
+    receiveMessageNumber: obj.receiveMessageNumber,
+    previousSendingChainLength: obj.previousSendingChainLength,
+    skippedMessageKeys: new Map(
+      Object.entries(obj.skippedMessageKeys).map(([k, v]) => [k, fromHex(v)]),
+    ),
+  };
+}

package/src/persistence/types.ts

@@ -0,0 +1,33 @@
+// ============================================================
+// MeshWhisper SDK — Persistence Types
+// ============================================================
+
+/**
+ * Minimal key-value storage interface. Implement this for your platform:
+ *   - Node.js:      NodeStorage (provided)
+ *   - React Native: AsyncStorage or SQLCipher wrapper
+ *   - Browser:      IndexedDB wrapper
+ *
+ * Values are always JSON strings. Keys use forward-slash namespacing:
+ *   identity, sessions/<peerId>, peers/<peerId>, contacts, messages/<peerId>, seen_ids
+ */
+export interface StorageBackend {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** Returns all stored keys that start with the given prefix. */
+  keys(prefix: string): Promise<string[]>;
+}
+
+export interface StoredMessage {
+  id: string;
+  /** The peer ID of the other party in this conversation. */
+  conversationId: string;
+  senderId: string;
+  recipientId: string;
+  /** Message payload as a plain number array (JSON-serialisable Uint8Array). */
+  payload: number[];
+  timestamp: number;
+  direction: 'inbound' | 'outbound';
+  status: 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
+}