ping-openmls-sdk-react-native-macos 0.2.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ping-openmls-sdk-react-native-macos",
+  "version": "0.2.0",
+  "description": "Real MLS for React Native macOS apps — wraps the ping-openmls-sdk Rust core via UniFFI.",
+  "homepage": "https://github.com/AMP-Media-Development/ping-openmls-sdk",
+  "license": "Apache-2.0",
+  "author": "Ping",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "ios",
+    "Frameworks",
+    "ping-openmls-sdk-react-native-macos.podspec",
+    "README.md"
+  ],
+  "keywords": [
+    "react-native",
+    "react-native-macos",
+    "mls",
+    "openmls",
+    "e2ee"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.73",
+    "react-native-macos": ">=0.73"
+  },
+  "codegenConfig": {
+    "name": "PingNativeSpec",
+    "type": "modules",
+    "jsSrcsDir": "src"
+  }
+}

package/ping-openmls-sdk-react-native-macos.podspec

@@ -0,0 +1,54 @@
+# CocoaPods descriptor for `ping-openmls-sdk-react-native-macos`.
+#
+# RN's autolinking discovers this file via the `react-native.config.js` of consumer apps
+# (or via Microsoft's `react-native-macos` autolinking script for macOS targets) and
+# generates the `pod 'ping-openmls-sdk-react-native-macos'` line in the host's Podfile.
+#
+# Spec: docs/RN_NATIVE_BINDINGS.md (stage 2).
+
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  # CocoaPods Pod names cannot contain `@` or `/` (those are reserved — `/` means subspec).
+  # The npm package is `ping-openmls-sdk-react-native-macos` but the Pod name has to be
+  # the hyphenated, unscoped form. RN's autolinker discovers this podspec via
+  # `react-native.config.js` (sibling file) and translates between the two names.
+  s.name         = 'ping-openmls-sdk-react-native-macos'
+  s.version      = package['version']
+  s.summary      = package['description']
+  s.homepage     = package['homepage']
+  # SPDX identifier only — pointing at `:file => '../../LICENSE'` would resolve from the
+  # package's install location under `node_modules/`, where the relative path doesn't
+  # reach the repo root. CocoaPods accepts a bare SPDX string for the license type.
+  s.license      = package['license']
+  s.authors      = { 'Ping' => 'https://github.com/AMP-Media-Development' }
+
+  # macOS-only Pod. The directory is named `ios/` to match the conventional CocoaPods
+  # layout, but the platform target is macOS — react-native-macos uses the iOS Pod
+  # tooling because it shares the AppKit-on-Cocoa codepath, even though the deployment
+  # target is `:osx`.
+  s.platforms    = { :osx => '10.15' }
+
+  s.source       = { :git => 'https://github.com/AMP-Media-Development/ping-openmls-sdk.git',
+                     :tag => "ping-openmls-sdk-rn-macos-v#{s.version}" }
+
+  s.source_files = 'ios/**/*.{h,m,mm,swift}'
+  s.public_header_files = 'ios/pingFFI.h'
+  s.preserve_paths = 'ios/module.modulemap', 'Frameworks/libping_ffi.a'
+
+  # Universal arm64+x86_64 static library produced by `scripts/build-macos.sh`. Static
+  # linking means the linker bakes the Rust code into the host app's binary at build
+  # time — no dylib to embed, no rpath setup, no runtime loading. This matches what the
+  # iOS pipeline does (see `scripts/build-ios.sh` → xcframework wraps a `.a`).
+  s.vendored_libraries = 'Frameworks/libping_ffi.a'
+
+  s.dependency 'React-Core'
+
+  s.pod_target_xcconfig = {
+    'SWIFT_INCLUDE_PATHS'  => '$(PODS_TARGET_SRCROOT)/ios',
+    'CLANG_ENABLE_MODULES' => 'YES',
+    'DEFINES_MODULE'       => 'YES'
+  }
+end

package/src/MessagingClient.ts

@@ -0,0 +1,488 @@
+// Public `MessagingClient` API for `ping-openmls-sdk-react-native-macos`. Mirrors the
+// shape of `ping-openmls-sdk`'s web SDK exactly so a desktop app can swap between the
+// two with a single import change.
+//
+// Stage 4b surface: `init`, `userId`, `deviceId`. Stages 4c–4f add the rest.
+//
+// Spec: docs/RN_NATIVE_BINDINGS.md (stage 4b).
+
+import { NativeEventEmitter, NativeModules } from "react-native";
+import NativePing from "./NativePing";
+import { connectStorageBridge, type Storage } from "./storage-bridge";
+import { connectTransportBridge, type Transport } from "./transport-bridge";
+
+export interface ClientConfig {
+  /**
+   * Identity export bytes. For a fresh device, generate via
+   * `MessagingClient.generateIdentity()`. For a returning device, load from secure
+   * storage (the bytes carry the long-term identity material).
+   */
+  identityExport: Uint8Array;
+  /** Human-readable label for this device (shown to users in device lists). */
+  deviceLabel: string;
+  /** Caller's storage backend. Wired into the native bridge during `init`. */
+  storage: Storage;
+  /** Caller's transport backend. Wired into the native bridge during `init`. */
+  transport: Transport;
+}
+
+/**
+ * High-level facade over the native MessagingClient. Methods marshal arguments + return
+ * values across the JS↔Swift bridge; the actual MLS work happens in Rust.
+ */
+export class MessagingClient {
+  /** Subscribers for incoming application messages (stage 4e). */
+  private readonly messageListeners = new Set<(msg: IncomingMessage) => void>();
+  /** Subscribers for conversation epoch changes (stage 4e). */
+  private readonly convUpdateListeners = new Set<(id: Uint8Array, epoch: number) => void>();
+  /** Native event subscriptions held while the client is alive. */
+  private observerSubscriptions: Array<{ remove(): void }> = [];
+  /** Transport's live-receive subscription, populated by init() if transport.subscribe exists. */
+  private transportSubscription?: { unsubscribe(): void };
+
+  private constructor(
+    private readonly disconnectStorage: () => void,
+    private readonly disconnectTransport: () => void,
+  ) {}
+
+  /**
+   * Construct a MessagingClient. Wires up the storage + transport bridges, then asks the
+   * native module to instantiate the underlying UniFFI handle.
+   */
+  static async init(cfg: ClientConfig): Promise<MessagingClient> {
+    // Connect bridges BEFORE calling native init — Rust's `MessagingClient::init` reads
+    // from storage during construction, so the JS handlers must be subscribed first.
+    const disconnectStorage = connectStorageBridge(cfg.storage);
+    const disconnectTransport = connectTransportBridge(cfg.transport);
+
+    try {
+      const identityB64 = bytesToBase64(cfg.identityExport);
+      await NativePing.initClient(identityB64, cfg.deviceLabel, Date.now());
+    } catch (e) {
+      // Init failed — disconnect the bridges so we don't leak event listeners.
+      disconnectStorage();
+      disconnectTransport();
+      throw e;
+    }
+
+    const client = new MessagingClient(disconnectStorage, disconnectTransport);
+
+    // Install the observer bridge so native can fire application-message and
+    // conversation-updated events. Failure here is non-fatal — the client still works
+    // for explicit `processEnvelope` / `syncConversations` calls.
+    try {
+      await client.installObserver();
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.warn("[ping-openmls-sdk-react-native-macos] observer install failed:", e);
+    }
+
+    // Auto-subscribe transport's live receive path. Dispatch on envelope kind:
+    //   - Welcome → joinConversation (the conv is, by definition, unknown until we join)
+    //   - Everything else → processEnvelope
+    // Both can fail silently — Welcomes are broadcast to all WS clients (only the
+    // recipient device succeeds), and non-Welcomes for unknown convs are
+    // foreign traffic we drop.
+    //
+    // Rust's `join_conversation` does NOT fire `on_conversation_updated` for the new
+    // conv (the observer is only invoked from `process_envelope` on epoch advances).
+    // We emit it manually here so consumers using `client.onConversationUpdated`
+    // see the join — matching what the web SDK's worker does.
+    if (cfg.transport.subscribe) {
+      const sub = cfg.transport.subscribe((envelopeJson) => {
+        void (async () => {
+          const kind = envelopeJson.kind;
+          // eslint-disable-next-line no-console
+          console.log("[ws-subscribe] received kind=" + String(kind));
+          try {
+            if (kind === "Welcome") {
+              const c = await client.joinConversation(envelopeJson);
+              // eslint-disable-next-line no-console
+              console.log("[ws-subscribe] joined conv id=" +
+                Array.from(c.id).map((b) => b.toString(16).padStart(2, "0")).join(""));
+              client.fireConvUpdated(c.id, 0);
+            } else {
+              await client.processEnvelope(envelopeJson);
+            }
+          } catch (e) {
+            // Expected for foreign Welcomes (other device's KP) or unknown-conv traffic.
+            // Logged for diagnostic value during stage 5 — drop to silent in production.
+            const msg = e instanceof Error ? e.message : String(e);
+            // eslint-disable-next-line no-console
+            console.log("[ws-subscribe] " + String(kind) + " dropped: " + msg.slice(0, 80));
+          }
+        })();
+      });
+      client.transportSubscription = sub;
+    }
+
+    return client;
+  }
+
+  /**
+   * Manually fire the `onConversationUpdated` listeners. Used by the auto-subscribe
+   * path to surface joins (since Rust's `join_conversation` doesn't trigger the
+   * observer).
+   */
+  private fireConvUpdated(id: Uint8Array, epoch: number): void {
+    for (const cb of this.convUpdateListeners) cb(id, epoch);
+  }
+
+  private async installObserver(): Promise<void> {
+    await NativePing.setObserver();
+
+    const emitter = new NativeEventEmitter(NativeModules.PingNative);
+    this.observerSubscriptions.push(
+      emitter.addListener("PingApplicationMessage", (raw: Record<string, unknown>) => {
+        const msg = decodeIncomingMessage(raw);
+        for (const cb of this.messageListeners) cb(msg);
+      }),
+      emitter.addListener(
+        "PingConversationUpdated",
+        (raw: { conversation_id?: number[]; new_epoch?: number }) => {
+          const id = bytesFrom(raw.conversation_id);
+          const epoch = Number(raw.new_epoch ?? 0);
+          for (const cb of this.convUpdateListeners) cb(id, epoch);
+        },
+      ),
+    );
+  }
+
+  /**
+   * Generate a fresh identity. Returns the bytes that should be persisted by the caller
+   * and passed back as `identityExport` on subsequent launches.
+   *
+   * Calls into Rust via UniFFI's `generateIdentityExport()` free function — the bytes
+   * are a properly-formatted Identity export (Ed25519 keypair + metadata, CBOR-encoded),
+   * not raw randomness. Persist them to secure storage; never log.
+   */
+  static async generateIdentity(): Promise<Uint8Array> {
+    const b64 = await NativePing.generateIdentityExport();
+    return base64ToBytes(b64);
+  }
+
+  /** This client's user id. Stable across launches for a given identity export. */
+  async userId(): Promise<Uint8Array> {
+    const hex = await NativePing.getUserId();
+    return hexToBytes(hex);
+  }
+
+  /** This client's device id. Stable across launches for a given identity + device label. */
+  async deviceId(): Promise<Uint8Array> {
+    const hex = await NativePing.getDeviceId();
+    return hexToBytes(hex);
+  }
+
+  /**
+   * Generate a fresh KeyPackage. Peers retrieve this (via the relay's directory or a
+   * join-code endpoint) and use it to add this device to their conversations.
+   */
+  async freshKeyPackage(): Promise<Uint8Array> {
+    const arr = await NativePing.freshKeyPackage();
+    return Uint8Array.from(arr);
+  }
+
+  /** Create a new conversation. Returns a `Conversation` handle. */
+  async createConversation(opts?: { name?: string | null }): Promise<Conversation> {
+    const idArr = await NativePing.createConversation(opts?.name ?? null, Date.now());
+    return new Conversation(this, Uint8Array.from(idArr));
+  }
+
+  /** Re-bind to an existing conversation by id (e.g. after a Welcome). */
+  getConversation(id: Uint8Array): Conversation {
+    return new Conversation(this, id);
+  }
+
+  /**
+   * Join a conversation from a Welcome envelope. Used by the auto-subscribe path in
+   * `init()` — when the transport's live stream delivers a Welcome and we don't yet
+   * track that conversation, we route to this method instead of `processEnvelope`.
+   *
+   * The relay broadcasts Welcomes to every connected device; only the device whose
+   * KeyPackage was used succeeds. Other devices throw an MLS-level error which the
+   * caller silently drops (they're "not for us").
+   */
+  async joinConversation(welcomeJson: Record<string, unknown>): Promise<Conversation> {
+    const idArr = await NativePing.joinConversation(welcomeJson, Date.now());
+    return new Conversation(this, Uint8Array.from(idArr));
+  }
+
+  /**
+   * Process an incoming envelope from the transport. Hosts that subscribe to the
+   * transport's live stream forward each frame here; returns the decrypted
+   * `IncomingMessage` for application traffic, or `null` for handshake messages
+   * (Commit/Welcome/Proposal — those advance MLS state without a user-visible payload).
+   */
+  async processEnvelope(envelope: Record<string, unknown>): Promise<IncomingMessage | null> {
+    const result = await NativePing.processEnvelope(envelope, Date.now());
+    return result ? decodeIncomingMessage(result) : null;
+  }
+
+  /**
+   * Catch-up sync — pull missed envelopes from the transport's `fetchSince` for every
+   * open conversation, apply them, and return the decrypted application messages in
+   * apply order.
+   */
+  async syncConversations(): Promise<IncomingMessage[]> {
+    const arr = await NativePing.syncConversations(Date.now());
+    return arr.map(decodeIncomingMessage);
+  }
+
+  /** Conversation metadata for every open conversation. */
+  async listConversations(): Promise<ConversationMeta[]> {
+    const arr = await NativePing.listConversations();
+    return arr.map(decodeConversationMeta);
+  }
+
+  /** Device info for every known device. v0.1: just the local device. */
+  async listDevices(): Promise<DeviceInfo[]> {
+    const arr = await NativePing.listDevices();
+    return arr.map(decodeDeviceInfo);
+  }
+
+  /**
+   * Subscribe to incoming application messages. Returns an unsubscribe function.
+   * Fires for every decrypted application payload — handshake messages
+   * (Welcome/Commit/Proposal) instead fire `onConversationUpdated`.
+   */
+  onMessage(callback: (msg: IncomingMessage) => void): () => void {
+    this.messageListeners.add(callback);
+    return () => this.messageListeners.delete(callback);
+  }
+
+  /**
+   * Subscribe to conversation epoch changes. Fires when a Welcome lands (new conv) or
+   * a Commit advances an existing conv to a new epoch.
+   */
+  onConversationUpdated(callback: (id: Uint8Array, newEpoch: number) => void): () => void {
+    this.convUpdateListeners.add(callback);
+    return () => this.convUpdateListeners.delete(callback);
+  }
+
+  /**
+   * Build a linking ticket for a new device. The new device has just published its
+   * KeyPackage (`newDeviceKp`); this builds an HPKE-wrapped Welcome to the user's
+   * DeviceGroup plus a catch-up snapshot. The new device consumes via
+   * `consumeLinkingTicket`.
+   */
+  async buildLinkingTicket(
+    newDeviceId: Uint8Array,
+    newDeviceKp: Uint8Array,
+  ): Promise<LinkingTicket> {
+    const raw = await NativePing.buildLinkingTicket(
+      Array.from(newDeviceId),
+      Array.from(newDeviceKp),
+      Date.now(),
+    );
+    return decodeLinkingTicket(raw);
+  }
+
+  /** Consume a linking ticket on the new device. Joins the DeviceGroup. */
+  async consumeLinkingTicket(ticket: LinkingTicket): Promise<void> {
+    await NativePing.consumeLinkingTicket(encodeLinkingTicket(ticket), Date.now());
+  }
+
+  /** Revoke a device — issues Remove proposals across the user's groups. */
+  async revokeDevice(deviceId: Uint8Array): Promise<void> {
+    await NativePing.revokeDevice(Array.from(deviceId), Date.now());
+  }
+
+  /** Detach storage + transport + observer listeners. Call when you're done. */
+  close(): void {
+    this.transportSubscription?.unsubscribe();
+    this.transportSubscription = undefined;
+    for (const sub of this.observerSubscriptions) sub.remove();
+    this.observerSubscriptions = [];
+    this.messageListeners.clear();
+    this.convUpdateListeners.clear();
+    this.disconnectStorage();
+    this.disconnectTransport();
+  }
+}
+
+/** Decrypted incoming message — application-layer payload + metadata. */
+export interface IncomingMessage {
+  conversationId: Uint8Array;
+  senderDevice: Uint8Array;
+  epoch: number;
+  hlc: { wallMs: number; logical: number };
+  plaintext: Uint8Array;
+  contentHash: Uint8Array;
+}
+
+/** Conversation metadata returned by `listConversations`. */
+export interface ConversationMeta {
+  id: Uint8Array;
+  name: string | null;
+  epoch: number;
+  memberCount: number;
+  isDeviceGroup: boolean;
+  createdAtMs: number;
+}
+
+/** Device metadata returned by `listDevices`. */
+export interface DeviceInfo {
+  deviceId: Uint8Array;
+  userId: Uint8Array;
+  label: string;
+  createdAtMs: number;
+  lastSeenMs: number;
+  revoked: boolean;
+}
+
+/** Linking ticket — bundle a new device's join package for an existing device to sign. */
+export interface LinkingTicket {
+  v: number;
+  userId: Uint8Array;
+  userPubkey: Uint8Array;
+  newDeviceId: Uint8Array;
+  deviceBindingSig: Uint8Array;
+  deviceGroupWelcome: Uint8Array;
+  catchupSnapshot: Uint8Array;
+}
+
+function decodeIncomingMessage(d: Record<string, unknown>): IncomingMessage {
+  const hlc = d.hlc as { wall_ms?: number; logical?: number } | undefined;
+  return {
+    conversationId: bytesFrom(d.conversation_id),
+    senderDevice:   bytesFrom(d.sender_device),
+    epoch:          Number(d.epoch ?? 0),
+    hlc:            { wallMs: hlc?.wall_ms ?? 0, logical: hlc?.logical ?? 0 },
+    plaintext:      bytesFrom(d.plaintext),
+    contentHash:    bytesFrom(d.content_hash),
+  };
+}
+
+function decodeConversationMeta(d: Record<string, unknown>): ConversationMeta {
+  return {
+    id:            bytesFrom(d.id),
+    name:          (d.name as string | null) ?? null,
+    epoch:         Number(d.epoch ?? 0),
+    memberCount:   Number(d.member_count ?? 0),
+    isDeviceGroup: Boolean(d.is_device_group),
+    createdAtMs:   Number(d.created_at_ms ?? 0),
+  };
+}
+
+function decodeDeviceInfo(d: Record<string, unknown>): DeviceInfo {
+  return {
+    deviceId:    bytesFrom(d.device_id),
+    userId:      bytesFrom(d.user_id),
+    label:       String(d.label ?? ""),
+    createdAtMs: Number(d.created_at_ms ?? 0),
+    lastSeenMs:  Number(d.last_seen_ms ?? 0),
+    revoked:     Boolean(d.revoked),
+  };
+}
+
+function decodeLinkingTicket(d: Record<string, unknown>): LinkingTicket {
+  return {
+    v:                  Number(d.v ?? 1),
+    userId:             bytesFrom(d.user_id),
+    userPubkey:         bytesFrom(d.user_pubkey),
+    newDeviceId:        bytesFrom(d.new_device_id),
+    deviceBindingSig:   bytesFrom(d.device_binding_sig),
+    deviceGroupWelcome: bytesFrom(d.device_group_welcome),
+    catchupSnapshot:    bytesFrom(d.catchup_snapshot),
+  };
+}
+
+function encodeLinkingTicket(t: LinkingTicket): Record<string, unknown> {
+  return {
+    v:                    t.v,
+    user_id:              Array.from(t.userId),
+    user_pubkey:          Array.from(t.userPubkey),
+    new_device_id:        Array.from(t.newDeviceId),
+    device_binding_sig:   Array.from(t.deviceBindingSig),
+    device_group_welcome: Array.from(t.deviceGroupWelcome),
+    catchup_snapshot:     Array.from(t.catchupSnapshot),
+  };
+}
+
+function bytesFrom(v: unknown): Uint8Array {
+  if (Array.isArray(v)) return Uint8Array.from(v as number[]);
+  return new Uint8Array(0);
+}
+
+/**
+ * Scoped handle for a single conversation. Mirrors `ping-openmls-sdk`'s `Conversation`
+ * class so the desktop demo can swap implementations with a single import change.
+ */
+export class Conversation {
+  constructor(
+    private readonly client: MessagingClient,
+    public readonly id: Uint8Array,
+  ) {}
+
+  /** Send an application message. Returns the wire envelope; the SDK has already pushed it through the transport. */
+  async send(plaintext: Uint8Array): Promise<Record<string, unknown>> {
+    return await NativePing.sendMessage(
+      Array.from(this.id),
+      Array.from(plaintext),
+      Date.now(),
+    );
+  }
+
+  /** Add members by their KeyPackage bytes (typically obtained via the relay's directory). */
+  async addMembers(keyPackages: Uint8Array[]): Promise<void> {
+    await NativePing.addMembers(
+      Array.from(this.id),
+      keyPackages.map((kp) => Array.from(kp)),
+      Date.now(),
+    );
+  }
+
+  /** Remove members by leaf index in the conversation's MLS ratchet tree. */
+  async removeMembers(leafIndexes: number[]): Promise<void> {
+    await NativePing.removeMembers(Array.from(this.id), leafIndexes, Date.now());
+  }
+}
+
+// ---------- helpers ----------
+
+// Base64 alphabet — standard, with `+/` and `=` padding.
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+function bytesToBase64(b: Uint8Array): string {
+  // Hermes doesn't ship `btoa`/`Buffer`; this is a small pure-JS encoder. Safe for any
+  // size; we only encode ~32B identity exports here so performance is not a concern.
+  let out = "";
+  let i = 0;
+  for (; i + 3 <= b.length; i += 3) {
+    const x = (b[i] << 16) | (b[i + 1] << 8) | b[i + 2];
+    out += B64[(x >> 18) & 63] + B64[(x >> 12) & 63] + B64[(x >> 6) & 63] + B64[x & 63];
+  }
+  const rem = b.length - i;
+  if (rem === 1) {
+    const x = b[i] << 16;
+    out += B64[(x >> 18) & 63] + B64[(x >> 12) & 63] + "==";
+  } else if (rem === 2) {
+    const x = (b[i] << 16) | (b[i + 1] << 8);
+    out += B64[(x >> 18) & 63] + B64[(x >> 12) & 63] + B64[(x >> 6) & 63] + "=";
+  }
+  return out;
+}
+
+function hexToBytes(s: string): Uint8Array {
+  if (s.length % 2 !== 0) throw new Error("odd-length hex");
+  const out = new Uint8Array(s.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/** Decode base64 to bytes. Mirror of bytesToBase64; same Hermes-compatible reasoning. */
+function base64ToBytes(s: string): Uint8Array {
+  const clean = s.replace(/[^A-Za-z0-9+/]/g, "");
+  const padded = clean.length % 4 === 2 ? clean + "==" : clean.length % 4 === 3 ? clean + "=" : clean;
+  const out: number[] = [];
+  for (let i = 0; i < padded.length; i += 4) {
+    const a = B64.indexOf(padded[i]);
+    const b = B64.indexOf(padded[i + 1]);
+    const c = padded[i + 2] === "=" ? -1 : B64.indexOf(padded[i + 2]);
+    const d = padded[i + 3] === "=" ? -1 : B64.indexOf(padded[i + 3]);
+    out.push((a << 2) | (b >> 4));
+    if (c >= 0) out.push(((b & 15) << 4) | (c >> 2));
+    if (d >= 0) out.push(((c & 3) << 6) | d);
+  }
+  return Uint8Array.from(out);
+}