@meshwhisper/sdk 0.1.0

package/src/types.ts

@@ -0,0 +1,275 @@
+// ============================================================
+// MeshWhisper SDK — Shared Types & Interfaces
+// All modules code against these types.
+// ============================================================
+
+// --- Crypto Types ---
+
+export interface KeyPair {
+  publicKey: Uint8Array;
+  privateKey: Uint8Array;
+}
+
+export interface PreKeyBundle {
+  identityKey: Uint8Array;
+  signedPreKey: Uint8Array;
+  signedPreKeySignature: Uint8Array;
+  oneTimePreKey?: Uint8Array;
+}
+
+export interface EncryptedPayload {
+  ciphertext: Uint8Array;
+  nonce: Uint8Array;
+  tag: Uint8Array;
+}
+
+// --- Packet Types ---
+
+export enum PacketFlags {
+  DATA = 0x01,
+  ACK = 0x02,
+  CHAFF = 0x03,
+  HANDSHAKE = 0x04,
+  ROUTE_REQUEST = 0x05,
+  ROUTE_OFFER = 0x06,
+}
+
+export interface Packet {
+  version: number;
+  flags: PacketFlags;
+  destHash: Uint8Array;       // 8 bytes — truncated BLAKE3
+  senderEphemeralId: Uint8Array; // 16 bytes — rotating
+  ttl: number;                // max 7
+  payloadLength: number;
+  encryptedPayload: Uint8Array;
+}
+
+// --- Transport Types ---
+
+export type BearerType = 'platform_p2p' | 'local_net' | 'internet';
+export type BatteryState = 'charging' | 'high' | 'medium' | 'low' | 'critical';
+export type RelayWillingness = 'eager' | 'willing' | 'reluctant' | 'unavailable';
+
+export interface DeviceCapability {
+  bearerPlatformP2P: boolean;
+  bearerLocalNet: boolean;
+  bearerInternet: boolean;
+  inboundConnectable: boolean;
+  batteryState: BatteryState;
+  relayWillingness: RelayWillingness;
+}
+
+export interface Transport {
+  readonly type: BearerType;
+  send(packet: Packet, destination: string): Promise<void>;
+  onReceive(callback: (packet: Packet, source: string) => void): void;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  isAvailable(): Promise<boolean>;
+}
+
+// --- Routing Types ---
+
+export interface PeerProximityEntry {
+  peerId: string;
+  destHash: Uint8Array;
+  lastSeen: number;
+  hopCount: number;
+  latency: number;
+  relayPath: string[];
+}
+
+export interface RouteRequest {
+  destHash: Uint8Array;
+  requestId: Uint8Array;
+  ttl: number;
+  timestamp: number;
+}
+
+export interface RouteOffer {
+  requestId: Uint8Array;
+  hopCount: number;
+  estimatedLatency: number;
+  offeredBy: string;
+}
+
+// --- Session Types ---
+
+export type PermissionModel = 'open' | 'mutual' | 'introduction' | 'transactional' | 'custom';
+
+export interface Session {
+  peerId: string;
+  namespaceId: Uint8Array;
+  sharedSecret: Uint8Array;
+  established: number;
+  lastActivity: number;
+}
+
+// --- Message Types ---
+
+export type MessageUrgency = 'background' | 'normal' | 'urgent' | 'critical';
+export type PresenceStatus = 'online' | 'recently_seen' | 'offline' | 'unknown';
+
+export interface Message {
+  id: string;
+  senderId: string;
+  recipientId: string;
+  payload: Uint8Array;
+  timestamp: number;
+  urgency: MessageUrgency;
+  expiry?: number;
+}
+
+// --- Group Types ---
+
+export interface GroupMember {
+  id: string;
+  senderKey: Uint8Array;
+  role: 'admin' | 'member';
+  joinedAt: number;
+}
+
+export interface Group {
+  id: string;
+  name: string;
+  members: Map<string, GroupMember>;
+  treeRoot: string;
+  permissionModel: PermissionModel;
+  createdAt: number;
+}
+
+// --- Reciprocity Types ---
+
+export interface RelayLedgerEntry {
+  peerId: string;
+  bytesRelayedForThem: number;
+  bytesTheyRelayedForUs: number;
+  lastUpdated: number;
+}
+
+export type ReciprocityTier = 'contributor' | 'balanced' | 'consumer' | 'freerider';
+
+// --- Cluster Types ---
+
+export interface ClusterDevice {
+  deviceId: string;
+  clusterKey: Uint8Array;
+  capabilities: DeviceCapability;
+  isPrimary: boolean;
+  lastSync: number;
+}
+
+// --- Store-and-Forward Types ---
+
+export interface StoredBlob {
+  id: string;
+  destHash: Uint8Array;
+  encryptedPayload: Uint8Array;
+  receivedAt: number;
+  ttlHours: number;
+  hopsRemaining: number;
+}
+
+// --- Sybil Resistance Types ---
+
+export type EntropySensorType = 'accelerometer' | 'gyroscope' | 'magnetometer';
+
+export interface EntropyChallenge {
+  challengeId: Uint8Array;
+  sensorType: EntropySensorType;
+  durationMs: number;
+  timestamp: number;
+}
+
+export interface EntropyResponse {
+  challengeId: Uint8Array;
+  sensorData: Float64Array;
+  deviceSignature: Uint8Array;
+}
+
+// --- Chaff Types ---
+
+export type ChaffRate = 'low' | 'normal' | 'high';
+
+// --- Compliance Types ---
+
+export type AuditExportMode = 'plaintext' | 'encrypted';
+
+export interface ComplianceConfig {
+  logging?: boolean;
+  auditExport?: AuditExportMode;
+  retentionDays?: number;
+  contentScanning?: (msg: Message) => { approved: boolean; reason?: string };
+}
+
+export type MessageHook = (message: Message) => boolean | Promise<boolean>;
+
+// --- SDK Config Types ---
+
+// Re-export persistence types so callers only need one import
+export type { StorageBackend, StoredMessage } from './persistence/types.js';
+
+/** Web Push subscription object (serialisable form of PushSubscription). */
+export interface WebPushSubscription {
+  endpoint: string;
+  expirationTime?: number | null;
+  keys: {
+    p256dh: string;
+    auth: string;
+  };
+}
+
+export type PushConfig =
+  | { platform: 'apns'; token: string; topic?: string }
+  | { platform: 'fcm'; token: string }
+  | { platform: 'webpush'; subscription: WebPushSubscription };
+
+export interface MeshWhisperConfig {
+  namespace: string;
+  /** MeshWhisper Node endpoint(s). Use "mesh" for Foundation-hosted nodes,
+   *  a wss:// URL for self-hosted, or an array for hybrid mode. Defaults to "mesh". */
+  node?: string | string[];
+  /** Optional developer key (base64 public key). If omitted a random key is used,
+   *  which is fine for development and single-tenant deployments. */
+  developerKey?: string;
+  /** Default: "open". */
+  permissionModel?: PermissionModel;
+  /** Push notification token. When set the Node stores the token alongside
+   *  the device's destination hashes and sends a wake signal via the configured
+   *  push webhook when a message arrives while the device is offline. */
+  push?: PushConfig;
+  /**
+   * Persistent storage backend. Provide this to survive process restarts:
+   * sessions, message history, identity, and contacts are all persisted.
+   *
+   * For Node.js: `import { NodeStorage } from '@meshwhisper/sdk/persistence/node'`
+   * For React Native: wrap AsyncStorage or SQLCipher.
+   */
+  storage?: import('./persistence/types.js').StorageBackend;
+  onMessage?: (message: Message) => void;
+  onPresence?: (peerId: string, status: PresenceStatus) => void;
+  /** Called when the delivery status of an outbound message changes. */
+  onMessageStatus?: (messageId: string, status: import('./persistence/types.js').StoredMessage['status']) => void;
+  config?: {
+    relayWillingness?: 'auto' | RelayWillingness;
+    chaffRate?: ChaffRate;
+    storeTTL?: number;       // hours, default 72
+    clusterEnabled?: boolean;
+  };
+}
+
+// --- Namespace Types ---
+
+export interface NamespaceConfig {
+  appBundleId: string;
+  developerPublicKey: Uint8Array;
+  salt: Uint8Array;
+}
+
+// --- Event Emitter ---
+
+export interface EventEmitter<T extends Record<string, unknown>> {
+  on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void;
+  off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void;
+  emit<K extends keyof T>(event: K, data: T[K]): void;
+}

package/src/x3dh/index.ts

@@ -0,0 +1,388 @@
+// ============================================================
+// MeshWhisper SDK — X3DH Key Exchange Module
+// Extended Triple Diffie-Hellman adapted for serverless P2P
+// ============================================================
+
+import { x25519, ed25519 } from '@noble/curves/ed25519';
+import { blake3 } from '@noble/hashes/blake3';
+import type { KeyPair, PreKeyBundle } from '../types.js';
+
+// --- Constants ---
+
+/** Protocol version for serialized pre-key bundles. */
+const BUNDLE_VERSION = 0x01;
+
+/** Length of an X25519/Ed25519 public key in bytes. */
+const KEY_LENGTH = 32;
+
+/** Length of an Ed25519 signature in bytes. */
+const SIGNATURE_LENGTH = 64;
+
+// --- Key Generation ---
+
+/**
+ * The result of generating a pre-key bundle. The bundle is the public
+ * portion distributed to peers; the key pairs must be stored locally
+ * so that X3DH can be completed on the responder side.
+ */
+export interface GeneratedPreKeyBundle {
+  /** The public bundle to distribute (gossip or directory). */
+  bundle: PreKeyBundle;
+  /** The X25519 signed pre-key pair. Store the private key. */
+  signedPreKeyPair: KeyPair;
+  /** The X25519 one-time pre-key pair. Store the private key. */
+  oneTimePreKeyPair: KeyPair;
+}
+
+/**
+ * Generates a full PreKeyBundle for distribution to peers.
+ *
+ * The bundle contains:
+ * - Identity key (Ed25519 public key from the provided key pair)
+ * - Signed pre-key (X25519, signed by the identity key)
+ * - One-time pre-key (X25519, single-use)
+ *
+ * The returned `signedPreKeyPair` and `oneTimePreKeyPair` private keys
+ * must be stored by the caller — they are required to complete X3DH on
+ * the responder side when a handshake arrives.
+ *
+ * @param identityKeyPair - Ed25519 identity key pair
+ * @returns Bundle (public) plus the key pairs (private keys must be stored)
+ */
+export function generatePreKeyBundle(identityKeyPair: KeyPair): GeneratedPreKeyBundle {
+  // Generate signed pre-key (X25519)
+  const signedPreKeyPrivate = x25519.utils.randomSecretKey();
+  const signedPreKeyPublic = x25519.getPublicKey(signedPreKeyPrivate);
+
+  // Sign the signed pre-key's public key with the Ed25519 identity key
+  const signature = ed25519.sign(signedPreKeyPublic, identityKeyPair.privateKey);
+
+  // Generate one-time pre-key (X25519)
+  const oneTimePreKeyPrivate = x25519.utils.randomSecretKey();
+  const oneTimePreKeyPublic = x25519.getPublicKey(oneTimePreKeyPrivate);
+
+  return {
+    bundle: {
+      identityKey: identityKeyPair.publicKey,
+      signedPreKey: signedPreKeyPublic,
+      signedPreKeySignature: signature,
+      oneTimePreKey: oneTimePreKeyPublic,
+    },
+    signedPreKeyPair: {
+      publicKey: signedPreKeyPublic,
+      privateKey: signedPreKeyPrivate,
+    },
+    oneTimePreKeyPair: {
+      publicKey: oneTimePreKeyPublic,
+      privateKey: oneTimePreKeyPrivate,
+    },
+  };
+}
+
+/**
+ * Generates a batch of one-time pre-keys for replenishment.
+ *
+ * Returns full KeyPairs — the caller must store the private keys.
+ * Only public keys are distributed in the prekey bundle; private keys
+ * are required locally to complete X3DH when a matching handshake arrives.
+ *
+ * @param _identityKeyPair - Unused; kept for API consistency
+ * @param count - Number of one-time pre-keys to generate
+ * @returns Array of X25519 key pairs
+ */
+export function generateOneTimePreKeys(
+  _identityKeyPair: KeyPair,
+  count: number,
+): KeyPair[] {
+  if (count < 0 || !Number.isInteger(count)) {
+    throw new Error('count must be a non-negative integer');
+  }
+
+  const keys: KeyPair[] = [];
+  for (let i = 0; i < count; i++) {
+    const privateKey = x25519.utils.randomSecretKey();
+    keys.push({ privateKey, publicKey: x25519.getPublicKey(privateKey) });
+  }
+  return keys;
+}
+
+// --- Key Exchange: Initiator (Alice) ---
+
+export interface KeyExchangeResult {
+  /** Derived shared secret (BLAKE3 hash of concatenated DH outputs). */
+  sharedSecret: Uint8Array;
+  /** Ephemeral X25519 public key Alice used — must be sent to Bob. */
+  ephemeralPublicKey: Uint8Array;
+  /** Whether a one-time pre-key was consumed in the exchange. */
+  usedOneTimePreKey: boolean;
+}
+
+/**
+ * Performs the initiator side (Alice) of the X3DH key exchange.
+ *
+ * Executes 3 or 4 DH operations:
+ *   DH1 = DH(IK_A, SPK_B) — Alice's identity key with Bob's signed pre-key
+ *   DH2 = DH(EK_A, IK_B)  — Alice's ephemeral key with Bob's identity key
+ *   DH3 = DH(EK_A, SPK_B) — Alice's ephemeral key with Bob's signed pre-key
+ *   DH4 = DH(EK_A, OPK_B) — Alice's ephemeral key with Bob's one-time pre-key (optional)
+ *
+ * The shared secret is derived as BLAKE3(DH1 || DH2 || DH3 [|| DH4]).
+ *
+ * @param aliceIdentity - Alice's Ed25519 identity key pair
+ * @param bobPreKeyBundle - Bob's published PreKeyBundle
+ * @returns The derived shared secret, ephemeral public key, and OPK usage flag
+ * @throws If the pre-key bundle signature is invalid
+ */
+export function initiateKeyExchange(
+  aliceIdentity: KeyPair,
+  bobPreKeyBundle: PreKeyBundle,
+): KeyExchangeResult {
+  // Verify Bob's signed pre-key before proceeding
+  if (!verifyPreKeyBundle(bobPreKeyBundle)) {
+    throw new Error('Invalid pre-key bundle: signed pre-key signature verification failed');
+  }
+
+  // Convert Alice's Ed25519 identity key to X25519 for DH operations
+  const aliceIdentityX25519Private = ed25519.utils.toMontgomerySecret(aliceIdentity.privateKey);
+
+  // Convert Bob's Ed25519 identity public key to X25519
+  const bobIdentityX25519Public = ed25519.utils.toMontgomery(bobPreKeyBundle.identityKey);
+
+  // Generate Alice's ephemeral X25519 key pair
+  const ephemeralPrivate = x25519.utils.randomSecretKey();
+  const ephemeralPublic = x25519.getPublicKey(ephemeralPrivate);
+
+  // DH1: DH(IK_A, SPK_B)
+  const dh1 = x25519.getSharedSecret(aliceIdentityX25519Private, bobPreKeyBundle.signedPreKey);
+
+  // DH2: DH(EK_A, IK_B)
+  const dh2 = x25519.getSharedSecret(ephemeralPrivate, bobIdentityX25519Public);
+
+  // DH3: DH(EK_A, SPK_B)
+  const dh3 = x25519.getSharedSecret(ephemeralPrivate, bobPreKeyBundle.signedPreKey);
+
+  // DH4: DH(EK_A, OPK_B) — optional
+  const usedOneTimePreKey = bobPreKeyBundle.oneTimePreKey != null;
+  let dhConcat: Uint8Array;
+
+  if (usedOneTimePreKey) {
+    const dh4 = x25519.getSharedSecret(ephemeralPrivate, bobPreKeyBundle.oneTimePreKey!);
+    dhConcat = concatBytes(dh1, dh2, dh3, dh4);
+  } else {
+    dhConcat = concatBytes(dh1, dh2, dh3);
+  }
+
+  // Derive shared secret via BLAKE3
+  const sharedSecret = blake3(dhConcat);
+
+  return {
+    sharedSecret,
+    ephemeralPublicKey: ephemeralPublic,
+    usedOneTimePreKey,
+  };
+}
+
+// --- Key Exchange: Responder (Bob) ---
+
+/**
+ * Performs the responder side (Bob) of the X3DH key exchange.
+ *
+ * Mirrors the initiator's DH operations to derive the same shared secret:
+ *   DH1 = DH(SPK_B, IK_A) — Bob's signed pre-key with Alice's identity key
+ *   DH2 = DH(IK_B, EK_A)  — Bob's identity key with Alice's ephemeral key
+ *   DH3 = DH(SPK_B, EK_A) — Bob's signed pre-key with Alice's ephemeral key
+ *   DH4 = DH(OPK_B, EK_A) — Bob's one-time pre-key with Alice's ephemeral key (optional)
+ *
+ * @param bobIdentity - Bob's Ed25519 identity key pair
+ * @param bobSignedPreKey - Bob's X25519 signed pre-key pair
+ * @param bobOneTimePreKey - Bob's X25519 one-time pre-key pair (null if not used)
+ * @param aliceIdentityKey - Alice's Ed25519 identity public key
+ * @param aliceEphemeralKey - Alice's X25519 ephemeral public key
+ * @returns The derived shared secret (same as Alice's if inputs are correct)
+ */
+export function completeKeyExchange(
+  bobIdentity: KeyPair,
+  bobSignedPreKey: KeyPair,
+  bobOneTimePreKey: KeyPair | null,
+  aliceIdentityKey: Uint8Array,
+  aliceEphemeralKey: Uint8Array,
+): Uint8Array {
+  // Convert Alice's Ed25519 identity public key to X25519
+  const aliceIdentityX25519Public = ed25519.utils.toMontgomery(aliceIdentityKey);
+
+  // Convert Bob's Ed25519 identity key to X25519
+  const bobIdentityX25519Private = ed25519.utils.toMontgomerySecret(bobIdentity.privateKey);
+
+  // DH1: DH(SPK_B, IK_A) — mirrors Alice's DH(IK_A, SPK_B)
+  const dh1 = x25519.getSharedSecret(bobSignedPreKey.privateKey, aliceIdentityX25519Public);
+
+  // DH2: DH(IK_B, EK_A) — mirrors Alice's DH(EK_A, IK_B)
+  const dh2 = x25519.getSharedSecret(bobIdentityX25519Private, aliceEphemeralKey);
+
+  // DH3: DH(SPK_B, EK_A) — mirrors Alice's DH(EK_A, SPK_B)
+  const dh3 = x25519.getSharedSecret(bobSignedPreKey.privateKey, aliceEphemeralKey);
+
+  // DH4: DH(OPK_B, EK_A) — optional
+  let dhConcat: Uint8Array;
+
+  if (bobOneTimePreKey != null) {
+    const dh4 = x25519.getSharedSecret(bobOneTimePreKey.privateKey, aliceEphemeralKey);
+    dhConcat = concatBytes(dh1, dh2, dh3, dh4);
+  } else {
+    dhConcat = concatBytes(dh1, dh2, dh3);
+  }
+
+  // Derive shared secret via BLAKE3
+  return blake3(dhConcat);
+}
+
+// --- PreKey Bundle Verification ---
+
+/**
+ * Verifies the signed pre-key signature in a PreKeyBundle.
+ *
+ * Checks that the signedPreKey was signed by the holder of the identityKey
+ * using Ed25519.
+ *
+ * @param bundle - The PreKeyBundle to verify
+ * @returns true if the signature is valid, false otherwise
+ */
+export function verifyPreKeyBundle(bundle: PreKeyBundle): boolean {
+  try {
+    return ed25519.verify(
+      bundle.signedPreKeySignature,
+      bundle.signedPreKey,
+      bundle.identityKey,
+    );
+  } catch {
+    return false;
+  }
+}
+
+// --- Serialization ---
+
+/**
+ * Serializes a PreKeyBundle to a compact binary format for gossip distribution.
+ *
+ * Wire format:
+ *   [version: 1 byte]
+ *   [flags: 1 byte]       — bit 0: hasOneTimePreKey
+ *   [identityKey: 32 bytes]
+ *   [signedPreKey: 32 bytes]
+ *   [signedPreKeySignature: 64 bytes]
+ *   [oneTimePreKey: 32 bytes]  — optional, present if flags bit 0 is set
+ *
+ * Total: 130 bytes without OPK, 162 bytes with OPK.
+ *
+ * @param bundle - The PreKeyBundle to serialize
+ * @returns Serialized binary representation
+ */
+export function serializePreKeyBundle(bundle: PreKeyBundle): Uint8Array {
+  const hasOPK = bundle.oneTimePreKey != null;
+  const flags = hasOPK ? 0x01 : 0x00;
+  const totalLength = 1 + 1 + KEY_LENGTH + KEY_LENGTH + SIGNATURE_LENGTH + (hasOPK ? KEY_LENGTH : 0);
+
+  const data = new Uint8Array(totalLength);
+  let offset = 0;
+
+  // Version
+  data[offset++] = BUNDLE_VERSION;
+
+  // Flags
+  data[offset++] = flags;
+
+  // Identity key
+  data.set(bundle.identityKey, offset);
+  offset += KEY_LENGTH;
+
+  // Signed pre-key
+  data.set(bundle.signedPreKey, offset);
+  offset += KEY_LENGTH;
+
+  // Signed pre-key signature
+  data.set(bundle.signedPreKeySignature, offset);
+  offset += SIGNATURE_LENGTH;
+
+  // One-time pre-key (optional)
+  if (hasOPK) {
+    data.set(bundle.oneTimePreKey!, offset);
+  }
+
+  return data;
+}
+
+/**
+ * Deserializes a PreKeyBundle from its binary representation.
+ *
+ * @param data - Serialized PreKeyBundle bytes
+ * @returns The deserialized PreKeyBundle
+ * @throws If the data is malformed or has an unsupported version
+ */
+export function deserializePreKeyBundle(data: Uint8Array): PreKeyBundle {
+  if (data.length < 2) {
+    throw new Error('PreKeyBundle data too short: missing header');
+  }
+
+  let offset = 0;
+
+  // Version
+  const version = data[offset++];
+  if (version !== BUNDLE_VERSION) {
+    throw new Error(`Unsupported PreKeyBundle version: ${version}`);
+  }
+
+  // Flags
+  const flags = data[offset++];
+  const hasOPK = (flags & 0x01) !== 0;
+
+  const expectedLength = 1 + 1 + KEY_LENGTH + KEY_LENGTH + SIGNATURE_LENGTH + (hasOPK ? KEY_LENGTH : 0);
+  if (data.length < expectedLength) {
+    throw new Error(
+      `PreKeyBundle data too short: expected ${expectedLength} bytes, got ${data.length}`,
+    );
+  }
+
+  // Identity key
+  const identityKey = data.slice(offset, offset + KEY_LENGTH);
+  offset += KEY_LENGTH;
+
+  // Signed pre-key
+  const signedPreKey = data.slice(offset, offset + KEY_LENGTH);
+  offset += KEY_LENGTH;
+
+  // Signed pre-key signature
+  const signedPreKeySignature = data.slice(offset, offset + SIGNATURE_LENGTH);
+  offset += SIGNATURE_LENGTH;
+
+  // One-time pre-key (optional)
+  const oneTimePreKey = hasOPK
+    ? data.slice(offset, offset + KEY_LENGTH)
+    : undefined;
+
+  return {
+    identityKey,
+    signedPreKey,
+    signedPreKeySignature,
+    oneTimePreKey,
+  };
+}
+
+// --- Utility ---
+
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array.
+ */
+function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+  let totalLength = 0;
+  for (const arr of arrays) {
+    totalLength += arr.length;
+  }
+
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}