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

package/ios/PingNativeModule.swift

@@ -0,0 +1,656 @@
+// Stage 3 entry point for the ping-openmls-sdk-react-native-macos native module.
+//
+// Stage 2 provided a static smoke test (`getWireContractVersion()`).
+// Stage 3 adds the JS↔Rust callback bridge. The hard problem: UniFFI generates Swift
+// `Storage` and `Transport` protocols that the Rust core calls into asynchronously. Our
+// implementations of those protocols must reach into JS — which lives on a different
+// thread, behind RN's bridge. We can't block. We can't synchronously call JS.
+//
+// Solution: per-call UUIDs + Swift continuations + RCTEventEmitter events.
+//
+//   1. Rust calls our Swift Storage.get(ns, key)
+//   2. Swift wraps in `withCheckedThrowingContinuation`, stores keyed by UUID
+//   3. Swift emits "PingStorageCall" event with { id, method, args } payload
+//   4. JS event listener receives it, invokes the user-supplied storage object
+//   5. JS calls back into native: PingNative.resolveStorageCall(id, value) (or reject)
+//   6. Swift looks up the continuation by id, resumes it with the result
+//   7. Rust gets its return value
+//
+// Stage 4 builds on this to wire the full MessagingClient surface.
+//
+// Spec: docs/RN_NATIVE_BINDINGS.md (stage 3).
+
+import AppKit
+import Foundation
+import React
+
+@objc(PingNative)
+public final class PingNative: RCTEventEmitter {
+
+    /// Singleton-ish instance reference. RCTEventEmitter is instantiated by RN's bridge;
+    /// the bridge module hooks below need to find the live instance to dispatch events.
+    /// We keep a weak reference because RN owns the lifecycle.
+    private static weak var shared: PingNative?
+
+    /// Bridges live for the lifetime of the module instance. Stage 4 will tie their
+    /// lifecycle to MessagingClient.init/close.
+    private lazy var storageBridge = JSStorageBridge { [weak self] id, method, args in
+        self?.sendEvent(withName: "PingStorageCall", body: [
+            "id": id, "method": method, "args": args,
+        ])
+    }
+    private lazy var transportBridge = JSTransportBridge { [weak self] id, method, args in
+        self?.sendEvent(withName: "PingTransportCall", body: [
+            "id": id, "method": method, "args": args,
+        ])
+    }
+
+    /// The active MessagingClient. One per native module instance (one per app process).
+    /// Stage 4b populates this in `initClient`; subsequent stage 4c/4d/4e/4f methods
+    /// dispatch through it.
+    private var client: MessagingClient?
+
+    /// Observer bridge — held strongly here because the UniFFI client only stores a
+    /// foreign-callback handle; the actual Swift instance is ours to keep alive.
+    private var observerBridge: JSObserverBridge?
+
+    // MARK: - RCTEventEmitter overrides
+
+    public override init() {
+        super.init()
+        PingNative.shared = self
+    }
+
+    @objc public override static func requiresMainQueueSetup() -> Bool { false }
+
+    public override func supportedEvents() -> [String] {
+        [
+            "PingStorageCall",         // stage 3 — Storage callbacks
+            "PingTransportCall",       // stage 3 — Transport callbacks
+            "PingApplicationMessage",  // stage 4e — observer: incoming application messages
+            "PingConversationUpdated", // stage 4e — observer: conversation epoch changes
+        ]
+    }
+
+    /// RN warns if observers aren't attached when events fire. Override these to
+    /// silence warnings + skip dispatch when no JS side is listening.
+    public override func startObserving() {}
+    public override func stopObserving() {}
+
+    // MARK: - Smoke test (stage 2 carryover)
+
+    @objc(getWireContractVersion:rejecter:)
+    public func getWireContractVersion(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        // Stage 4 replaces with `Generated.swift`'s `WIRE_VERSION`.
+        resolve(1)
+    }
+
+    // MARK: - Storage round-trip resolution (called from JS)
+
+    /// JS calls this when its storage handler has finished. `value` is `null` when the
+    /// storage operation returned no data (e.g. `get` on a missing key, or `put`/`del`
+    /// which return void).
+    @objc(resolveStorageCall:value:resolver:rejecter:)
+    public func resolveStorageCall(
+        _ id: String,
+        value: Any?,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        storageBridge.resolve(id: id, value: value)
+        resolve(NSNull())
+    }
+
+    /// JS calls this when its storage handler threw. The string becomes a `PingError`
+    /// on the Rust side.
+    @objc(rejectStorageCall:message:resolver:rejecter:)
+    public func rejectStorageCall(
+        _ id: String,
+        message: String,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        storageBridge.reject(id: id, message: message)
+        resolve(NSNull())
+    }
+
+    // MARK: - Transport round-trip resolution (called from JS)
+
+    @objc(resolveTransportCall:value:resolver:rejecter:)
+    public func resolveTransportCall(
+        _ id: String,
+        value: Any?,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        transportBridge.resolve(id: id, value: value)
+        resolve(NSNull())
+    }
+
+    @objc(rejectTransportCall:message:resolver:rejecter:)
+    public func rejectTransportCall(
+        _ id: String,
+        message: String,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        transportBridge.reject(id: id, message: message)
+        resolve(NSNull())
+    }
+
+    // MARK: - Storage round-trip self-test
+
+    /// Stage 3 acceptance test. Exercises the full Swift→JS→Swift round-trip without
+    /// involving Rust: calls bridge.put then bridge.get and verifies the values match.
+    /// Returns true on success.
+    ///
+    /// Stage 4 replaces this with calls into the real MessagingClient that flow through
+    /// the bridge automatically.
+    @objc(testStorageRoundtrip:rejecter:)
+    public func testStorageRoundtrip(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            do {
+                let probe = "stage3-probe-\(UUID().uuidString)".data(using: .utf8)!
+                try await storageBridge.put(namespace: "test", key: "probe", value: probe)
+                let got = try await storageBridge.get(namespace: "test", key: "probe")
+                guard got == probe else {
+                    reject("RoundtripMismatch", "stored bytes differed from retrieved bytes", nil)
+                    return
+                }
+                let keys = try await storageBridge.listKeys(namespace: "test", prefix: "")
+                guard keys.contains("probe") else {
+                    reject("RoundtripMismatch", "listKeys did not include probe", nil)
+                    return
+                }
+                try await storageBridge.delete(namespace: "test", key: "probe")
+                let after = try await storageBridge.get(namespace: "test", key: "probe")
+                guard after == nil else {
+                    reject("RoundtripMismatch", "probe still present after delete", nil)
+                    return
+                }
+                resolve(true)
+            } catch {
+                reject("RoundtripError", String(describing: error), error)
+            }
+        }
+    }
+
+    // MARK: - Identity helper (stage 4b — UDL addition)
+
+    /// Generate a fresh identity export. Returns the bytes as a base64 string for safe
+    /// transit across the bridge. Hosts persist the bytes and pass them back to
+    /// `initClient(identityB64:...)` on subsequent launches.
+    @objc(generateIdentityExport:rejecter:)
+    public func generateIdentityExportNative(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        // `generate_identity_export` is a UniFFI top-level free function. UniFFI's
+        // Swift output exposes it under camelCase: `generateIdentityExport()`.
+        let bytes = generateIdentityExport()
+        let b64 = Data(bytes).base64EncodedString()
+        resolve(b64)
+    }
+
+    // MARK: - MessagingClient lifecycle (stage 4b)
+
+    /// Construct a real `MessagingClient` via UniFFI, wired to our JS storage + transport
+    /// bridges. Caller should `connectStorageBridge(s)` and `connectTransportBridge(t)` on
+    /// the JS side before calling this so storage operations during init can resolve.
+    ///
+    /// `identityB64` is the base64-encoded identity export bytes. The desktop example
+    /// generates these via `crypto.getRandomValues` for v0.2 demo purposes; production
+    /// consumers will source persisted identity from secure storage.
+    ///
+    /// `nowMs` is the wall-clock at the call site (Hermes can't pass UInt64 across the
+    /// bridge precisely so we accept Double and truncate; valid for the next ~285,000
+    /// years of Unix time).
+    @objc(initClient:deviceLabel:nowMs:resolver:rejecter:)
+    public func initClient(
+        _ identityB64: String,
+        deviceLabel: String,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            do {
+                guard let identityData = Data(base64Encoded: identityB64) else {
+                    reject("InvalidIdentity", "identity bytes failed base64 decode", nil)
+                    return
+                }
+                // UniFFI's `[Name=init]` constructor generates a static factory named
+                // `init` (backquoted because Swift reserves the bare identifier for
+                // designated initializers).
+                let c = try await MessagingClient.`init`(
+                    identityExport: identityData,
+                    deviceLabel: deviceLabel,
+                    storage: self.storageBridge,
+                    transport: self.transportBridge,
+                    nowMs: UInt64(nowMs)
+                )
+                self.client = c
+                resolve(true)
+            } catch {
+                reject("InitFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Returns the user_id of the active client as a hex string. JS callers receive a
+    /// hex string and decode it themselves (avoids byte-array marshalling overhead for
+    /// a method that's likely called once at startup).
+    @objc(getUserId:rejecter:)
+    public func getUserId(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let client = self.client else {
+            reject("NotInitialised", "MessagingClient not initialised", nil)
+            return
+        }
+        let uid = client.userId()
+        resolve(uid.value.map { String(format: "%02x", $0) }.joined())
+    }
+
+    @objc(getDeviceId:rejecter:)
+    public func getDeviceId(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let client = self.client else {
+            reject("NotInitialised", "MessagingClient not initialised", nil)
+            return
+        }
+        let did = client.deviceId()
+        resolve(did.value.map { String(format: "%02x", $0) }.joined())
+    }
+
+    // MARK: - Messaging methods (stage 4c)
+
+    /// Generate a fresh KeyPackage that peers can use to add this device to their groups.
+    /// Synchronous on the Rust side but we wrap as a Promise for JS consistency.
+    @objc(freshKeyPackage:rejecter:)
+    public func freshKeyPackageNative(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let client = self.client else {
+            reject("NotInitialised", "MessagingClient not initialised", nil)
+            return
+        }
+        do {
+            let kp = try client.freshKeyPackage()
+            resolve(TypeBridge.encodeBytes(kp))
+        } catch {
+            reject("FreshKeyPackageFailed", String(describing: error), error)
+        }
+    }
+
+    /// Create a new conversation with `name` (optional). Returns the conversation id as
+    /// a `[Int]` byte array (16 bytes, ULID-encoded).
+    @objc(createConversation:nowMs:resolver:rejecter:)
+    public func createConversationNative(
+        _ name: NSString?,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let convName = name as String?
+                let convId = try await client.createConversation(name: convName, nowMs: UInt64(nowMs))
+                resolve(TypeBridge.encodeConversationId(convId))
+            } catch {
+                reject("CreateFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Join a conversation from a Welcome envelope. The relay broadcasts Welcomes to
+    /// every WS client; each client tries to join, and only the device whose KeyPackage
+    /// was used succeeds. Other devices fail with an MLS-level error which the caller
+    /// silently drops.
+    @objc(joinConversation:nowMs:resolver:rejecter:)
+    public func joinConversationNative(
+        _ welcomeDict: NSDictionary,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let welcome = try TypeBridge.decodeEnvelope(welcomeDict)
+                let convId = try await client.joinConversation(welcome: welcome, nowMs: UInt64(nowMs))
+                resolve(TypeBridge.encodeConversationId(convId))
+            } catch {
+                reject("JoinFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Send an application message in the given conversation. Returns the wire envelope
+    /// as a JSON-shaped dict (see TypeBridge.encodeEnvelope).
+    @objc(sendMessage:plaintext:nowMs:resolver:rejecter:)
+    public func sendMessageNative(
+        _ conversationIdBytes: NSArray,
+        plaintext plaintextBytes: NSArray,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let convId = try TypeBridge.decodeConversationId(conversationIdBytes)
+                let plaintext = try TypeBridge.decodeBytesOrThrow(plaintextBytes, field: "plaintext")
+                let env = try await client.send(
+                    conversationId: convId,
+                    plaintext: plaintext,
+                    nowMs: UInt64(nowMs)
+                )
+                resolve(TypeBridge.encodeEnvelope(env))
+            } catch {
+                reject("SendFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Add members to an existing conversation. `keyPackages` is an array of byte arrays
+    /// (each one a peer's KeyPackage from `freshKeyPackage`).
+    @objc(addMembers:keyPackages:nowMs:resolver:rejecter:)
+    public func addMembersNative(
+        _ conversationIdBytes: NSArray,
+        keyPackages keyPackagesArr: NSArray,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let convId = try TypeBridge.decodeConversationId(conversationIdBytes)
+                var kps: [Data] = []
+                for kp in keyPackagesArr {
+                    kps.append(try TypeBridge.decodeBytesOrThrow(kp, field: "keyPackage"))
+                }
+                try await client.addMembers(
+                    conversationId: convId,
+                    keyPackages: kps,
+                    nowMs: UInt64(nowMs)
+                )
+                resolve(NSNull())
+            } catch {
+                reject("AddMembersFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Remove members by leaf index. Leaf indexes come from `MlsGroup::members()` in
+    /// stage 4e's `listConversations` result; for now they're caller-supplied integers.
+    @objc(removeMembers:leafIndexes:nowMs:resolver:rejecter:)
+    public func removeMembersNative(
+        _ conversationIdBytes: NSArray,
+        leafIndexes indexes: NSArray,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let convId = try TypeBridge.decodeConversationId(conversationIdBytes)
+                var leaves: [UInt32] = []
+                for n in indexes {
+                    if let v = n as? NSNumber { leaves.append(v.uint32Value) }
+                }
+                try await client.removeMembers(
+                    conversationId: convId,
+                    leafIndexes: leaves,
+                    nowMs: UInt64(nowMs)
+                )
+                resolve(NSNull())
+            } catch {
+                reject("RemoveMembersFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    // MARK: - Sync methods (stage 4d)
+
+    /// Process a single incoming envelope from the wire. Returns the decrypted
+    /// `IncomingMessage` for `Application` kind envelopes, or `null` for handshake
+    /// kinds (Commit/Welcome/Proposal — those advance state without producing a
+    /// user-visible message).
+    ///
+    /// JS callers typically don't invoke this directly — `subscribe` on the transport
+    /// fans incoming envelopes here automatically. Exposed for completeness and tests.
+    @objc(processEnvelope:nowMs:resolver:rejecter:)
+    public func processEnvelopeNative(
+        _ envelopeDict: NSDictionary,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let env = try TypeBridge.decodeEnvelope(envelopeDict)
+                let result = try await client.processEnvelope(envelope: env, nowMs: UInt64(nowMs))
+                if let msg = result {
+                    resolve(TypeBridge.encodeIncomingMessage(msg))
+                } else {
+                    resolve(NSNull())
+                }
+            } catch {
+                reject("ProcessFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Catch-up sync. For each open conversation, calls the transport's `fetchSince`
+    /// (via the bridge), processes each returned envelope, and emits decrypted
+    /// `IncomingMessage`s. Returns the messages decoded since the last sync.
+    @objc(syncConversations:resolver:rejecter:)
+    public func syncConversationsNative(
+        _ nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let messages = try await client.syncConversations(nowMs: UInt64(nowMs))
+                resolve(TypeBridge.encodeIncomingMessageArray(messages))
+            } catch {
+                reject("SyncFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    // MARK: - Discovery + observer (stage 4e)
+
+    /// Returns metadata for every conversation the client knows about.
+    @objc(listConversations:rejecter:)
+    public func listConversationsNative(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let client = self.client else {
+            reject("NotInitialised", "MessagingClient not initialised", nil)
+            return
+        }
+        let metas = client.listConversations()
+        resolve(TypeBridge.encodeConversationMetaArray(metas))
+    }
+
+    /// Returns metadata for every device the client knows about (for v0.1, just the
+    /// local device — see ping-ffi/lib.rs note).
+    @objc(listDevices:rejecter:)
+    public func listDevicesNative(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let client = self.client else {
+            reject("NotInitialised", "MessagingClient not initialised", nil)
+            return
+        }
+        let devs = client.listDevices()
+        resolve(TypeBridge.encodeDeviceInfoArray(devs))
+    }
+
+    /// Install the observer bridge. After this, the client emits `PingApplicationMessage`
+    /// and `PingConversationUpdated` events as new state arrives. JS subscribes via
+    /// `client.onMessage` / `client.onConversationUpdated`.
+    ///
+    /// Idempotent — calling twice replaces the existing observer.
+    @objc(setObserver:rejecter:)
+    public func setObserverNative(
+        _ resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let client = self.client else {
+            reject("NotInitialised", "MessagingClient not initialised", nil)
+            return
+        }
+        let observer = JSObserverBridge { [weak self] name, body in
+            self?.sendEvent(withName: name, body: body)
+        }
+        self.observerBridge = observer
+        client.setObserver(observer: observer)
+        resolve(NSNull())
+    }
+
+    // MARK: - Linking + revocation (stage 4f)
+
+    /// Build a linking ticket on the existing device (E) for a new device (N) that
+    /// just published its KeyPackage. The ticket bundles a Welcome to E's DeviceGroup
+    /// plus a catch-up snapshot. N consumes the ticket via `consumeLinkingTicket`.
+    @objc(buildLinkingTicket:newDeviceKp:nowMs:resolver:rejecter:)
+    public func buildLinkingTicketNative(
+        _ newDeviceIdBytes: NSArray,
+        newDeviceKp newDeviceKpBytes: NSArray,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let newDeviceId = try TypeBridge.decodeDeviceId(newDeviceIdBytes)
+                let newKp = try TypeBridge.decodeBytesOrThrow(newDeviceKpBytes, field: "newDeviceKp")
+                let ticket = try await client.buildLinkingTicket(
+                    newDeviceId: newDeviceId,
+                    newDeviceKp: newKp,
+                    nowMs: UInt64(nowMs)
+                )
+                resolve(TypeBridge.encodeLinkingTicket(ticket))
+            } catch {
+                reject("LinkingFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Consume a linking ticket on the new device (N). Joins the user's DeviceGroup
+    /// using the embedded Welcome and applies the catch-up snapshot.
+    @objc(consumeLinkingTicket:nowMs:resolver:rejecter:)
+    public func consumeLinkingTicketNative(
+        _ ticketDict: NSDictionary,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let ticket = try TypeBridge.decodeLinkingTicket(ticketDict)
+                try await client.consumeLinkingTicket(
+                    ticket: ticket,
+                    nowMs: UInt64(nowMs)
+                )
+                resolve(NSNull())
+            } catch {
+                reject("ConsumeLinkingFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    /// Revoke a device — issues Remove proposals in the DeviceGroup and every external
+    /// conversation the device participates in. Post-revocation, the target device
+    /// can't decrypt new traffic (PCS).
+    @objc(revokeDevice:nowMs:resolver:rejecter:)
+    public func revokeDeviceNative(
+        _ deviceIdBytes: NSArray,
+        nowMs: Double,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        Task {
+            guard let client = self.client else {
+                reject("NotInitialised", "MessagingClient not initialised", nil)
+                return
+            }
+            do {
+                let deviceId = try TypeBridge.decodeDeviceId(deviceIdBytes)
+                try await client.revokeDevice(deviceId: deviceId, nowMs: UInt64(nowMs))
+                resolve(NSNull())
+            } catch {
+                reject("RevokeFailed", String(describing: error), error)
+            }
+        }
+    }
+
+    // MARK: - macOS clipboard helper (stage 5 polish)
+
+    /// Write a string to the macOS pasteboard. Hermes doesn't ship `navigator.clipboard`
+    /// out of the box, so the desktop example polyfills it via this method.
+    /// Pasteboard access must run on the main queue.
+    @objc(setClipboard:resolver:rejecter:)
+    public func setClipboardNative(
+        _ text: NSString,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            let pasteboard = NSPasteboard.general
+            pasteboard.clearContents()
+            pasteboard.setString(text as String, forType: .string)
+            resolve(NSNull())
+        }
+    }
+}