ping-openmls-sdk-react-native-macos 0.7.4 → 0.7.6

package/ios/Generated.swift

@@ -726,6 +726,8 @@ public func FfiConverterTypeMessageObserver_lower(_ value: MessageObserver) -> U
 public protocol MessagingClientProtocol: AnyObject {
     func addMembers(conversationId: ConversationId, entries: [KeyPackageEntry], nowMs: UInt64) async throws
 
+    func admitDeviceToChats(newDeviceId: DeviceId, entries: [AdmitChatEntry], nowMs: UInt64) async throws -> [AdmitChatOutcome]
+
     func buildLinkingTicket(newDeviceId: DeviceId, newDeviceKp: Data, lastAppEvents: [CatchupAppEvent], nowMs: UInt64) async throws -> LinkingTicket
 
     func consumeLinkingTicket(ticket: LinkingTicket, nowMs: UInt64) async throws
@@ -845,6 +847,23 @@ open class MessagingClient:
             )
     }
 
+    open func admitDeviceToChats(newDeviceId: DeviceId, entries: [AdmitChatEntry], nowMs: UInt64) async throws -> [AdmitChatOutcome] {
+        return
+            try await uniffiRustCallAsync(
+                rustFutureFunc: {
+                    uniffi_ping_ffi_fn_method_messagingclient_admit_device_to_chats(
+                        self.uniffiClonePointer(),
+                        FfiConverterTypeDeviceId.lower(newDeviceId), FfiConverterSequenceTypeAdmitChatEntry.lower(entries), FfiConverterUInt64.lower(nowMs)
+                    )
+                },
+                pollFunc: ffi_ping_ffi_rust_future_poll_rust_buffer,
+                completeFunc: ffi_ping_ffi_rust_future_complete_rust_buffer,
+                freeFunc: ffi_ping_ffi_rust_future_free_rust_buffer,
+                liftFunc: FfiConverterSequenceTypeAdmitChatOutcome.lift,
+                errorHandler: FfiConverterTypePingError.lift
+            )
+    }
+
     open func buildLinkingTicket(newDeviceId: DeviceId, newDeviceKp: Data, lastAppEvents: [CatchupAppEvent], nowMs: UInt64) async throws -> LinkingTicket {
         return
             try await uniffiRustCallAsync(
@@ -1811,6 +1830,144 @@ public func FfiConverterTypeTransport_lower(_ value: Transport) -> UnsafeMutable
     return FfiConverterTypeTransport.lower(value)
 }
 
+public struct AdmitChatEntry {
+    public var conversationId: ConversationId
+    public var keyPackage: Data
+
+    /// Default memberwise initializers are never public by default, so we
+    /// declare one manually.
+    public init(conversationId: ConversationId, keyPackage: Data) {
+        self.conversationId = conversationId
+        self.keyPackage = keyPackage
+    }
+}
+
+extension AdmitChatEntry: Equatable, Hashable {
+    public static func == (lhs: AdmitChatEntry, rhs: AdmitChatEntry) -> Bool {
+        if lhs.conversationId != rhs.conversationId {
+            return false
+        }
+        if lhs.keyPackage != rhs.keyPackage {
+            return false
+        }
+        return true
+    }
+
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(conversationId)
+        hasher.combine(keyPackage)
+    }
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAdmitChatEntry: FfiConverterRustBuffer {
+    public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AdmitChatEntry {
+        return
+            try AdmitChatEntry(
+                conversationId: FfiConverterTypeConversationId.read(from: &buf),
+                keyPackage: FfiConverterData.read(from: &buf)
+            )
+    }
+
+    public static func write(_ value: AdmitChatEntry, into buf: inout [UInt8]) {
+        FfiConverterTypeConversationId.write(value.conversationId, into: &buf)
+        FfiConverterData.write(value.keyPackage, into: &buf)
+    }
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAdmitChatEntry_lift(_ buf: RustBuffer) throws -> AdmitChatEntry {
+    return try FfiConverterTypeAdmitChatEntry.lift(buf)
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAdmitChatEntry_lower(_ value: AdmitChatEntry) -> RustBuffer {
+    return FfiConverterTypeAdmitChatEntry.lower(value)
+}
+
+public struct AdmitChatOutcome {
+    public var conversationId: ConversationId
+    public var status: AdmitChatStatus
+    public var reason: String?
+    public var error: String?
+
+    /// Default memberwise initializers are never public by default, so we
+    /// declare one manually.
+    public init(conversationId: ConversationId, status: AdmitChatStatus, reason: String?, error: String?) {
+        self.conversationId = conversationId
+        self.status = status
+        self.reason = reason
+        self.error = error
+    }
+}
+
+extension AdmitChatOutcome: Equatable, Hashable {
+    public static func == (lhs: AdmitChatOutcome, rhs: AdmitChatOutcome) -> Bool {
+        if lhs.conversationId != rhs.conversationId {
+            return false
+        }
+        if lhs.status != rhs.status {
+            return false
+        }
+        if lhs.reason != rhs.reason {
+            return false
+        }
+        if lhs.error != rhs.error {
+            return false
+        }
+        return true
+    }
+
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(conversationId)
+        hasher.combine(status)
+        hasher.combine(reason)
+        hasher.combine(error)
+    }
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAdmitChatOutcome: FfiConverterRustBuffer {
+    public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AdmitChatOutcome {
+        return
+            try AdmitChatOutcome(
+                conversationId: FfiConverterTypeConversationId.read(from: &buf),
+                status: FfiConverterTypeAdmitChatStatus.read(from: &buf),
+                reason: FfiConverterOptionString.read(from: &buf),
+                error: FfiConverterOptionString.read(from: &buf)
+            )
+    }
+
+    public static func write(_ value: AdmitChatOutcome, into buf: inout [UInt8]) {
+        FfiConverterTypeConversationId.write(value.conversationId, into: &buf)
+        FfiConverterTypeAdmitChatStatus.write(value.status, into: &buf)
+        FfiConverterOptionString.write(value.reason, into: &buf)
+        FfiConverterOptionString.write(value.error, into: &buf)
+    }
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAdmitChatOutcome_lift(_ buf: RustBuffer) throws -> AdmitChatOutcome {
+    return try FfiConverterTypeAdmitChatOutcome.lift(buf)
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAdmitChatOutcome_lower(_ value: AdmitChatOutcome) -> RustBuffer {
+    return FfiConverterTypeAdmitChatOutcome.lower(value)
+}
+
 public struct CatchupAppEvent {
     public var conversationId: ConversationId
     public var appEventBytes: Data
@@ -2852,6 +3009,64 @@ public func FfiConverterTypeUserId_lower(_ value: UserId) -> RustBuffer {
 // Note that we don't yet support `indirect` for enums.
 // See https://github.com/mozilla/uniffi-rs/issues/396 for further discussion.
 
+public enum AdmitChatStatus {
+    case admitted
+    case skipped
+    case failed
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAdmitChatStatus: FfiConverterRustBuffer {
+    typealias SwiftType = AdmitChatStatus
+
+    public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AdmitChatStatus {
+        let variant: Int32 = try readInt(&buf)
+        switch variant {
+        case 1: return .admitted
+
+        case 2: return .skipped
+
+        case 3: return .failed
+
+        default: throw UniffiInternalError.unexpectedEnumCase
+        }
+    }
+
+    public static func write(_ value: AdmitChatStatus, into buf: inout [UInt8]) {
+        switch value {
+        case .admitted:
+            writeInt(&buf, Int32(1))
+
+        case .skipped:
+            writeInt(&buf, Int32(2))
+
+        case .failed:
+            writeInt(&buf, Int32(3))
+        }
+    }
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAdmitChatStatus_lift(_ buf: RustBuffer) throws -> AdmitChatStatus {
+    return try FfiConverterTypeAdmitChatStatus.lift(buf)
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAdmitChatStatus_lower(_ value: AdmitChatStatus) -> RustBuffer {
+    return FfiConverterTypeAdmitChatStatus.lower(value)
+}
+
+extension AdmitChatStatus: Equatable, Hashable {}
+
+// Note that we don't yet support `indirect` for enums.
+// See https://github.com/mozilla/uniffi-rs/issues/396 for further discussion.
+
 public enum MessageKind {
     case application
     case commit
@@ -3150,6 +3365,56 @@ private struct FfiConverterSequenceString: FfiConverterRustBuffer {
     }
 }
 
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+private struct FfiConverterSequenceTypeAdmitChatEntry: FfiConverterRustBuffer {
+    typealias SwiftType = [AdmitChatEntry]
+
+    static func write(_ value: [AdmitChatEntry], into buf: inout [UInt8]) {
+        let len = Int32(value.count)
+        writeInt(&buf, len)
+        for item in value {
+            FfiConverterTypeAdmitChatEntry.write(item, into: &buf)
+        }
+    }
+
+    static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> [AdmitChatEntry] {
+        let len: Int32 = try readInt(&buf)
+        var seq = [AdmitChatEntry]()
+        seq.reserveCapacity(Int(len))
+        for _ in 0 ..< len {
+            try seq.append(FfiConverterTypeAdmitChatEntry.read(from: &buf))
+        }
+        return seq
+    }
+}
+
+#if swift(>=5.8)
+    @_documentation(visibility: private)
+#endif
+private struct FfiConverterSequenceTypeAdmitChatOutcome: FfiConverterRustBuffer {
+    typealias SwiftType = [AdmitChatOutcome]
+
+    static func write(_ value: [AdmitChatOutcome], into buf: inout [UInt8]) {
+        let len = Int32(value.count)
+        writeInt(&buf, len)
+        for item in value {
+            FfiConverterTypeAdmitChatOutcome.write(item, into: &buf)
+        }
+    }
+
+    static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> [AdmitChatOutcome] {
+        let len: Int32 = try readInt(&buf)
+        var seq = [AdmitChatOutcome]()
+        seq.reserveCapacity(Int(len))
+        for _ in 0 ..< len {
+            try seq.append(FfiConverterTypeAdmitChatOutcome.read(from: &buf))
+        }
+        return seq
+    }
+}
+
 #if swift(>=5.8)
     @_documentation(visibility: private)
 #endif
@@ -3532,6 +3797,9 @@ private var initializationResult: InitializationResult = {
     if uniffi_ping_ffi_checksum_method_messagingclient_add_members() != 2224 {
         return InitializationResult.apiChecksumMismatch
     }
+    if uniffi_ping_ffi_checksum_method_messagingclient_admit_device_to_chats() != 22080 {
+        return InitializationResult.apiChecksumMismatch
+    }
     if uniffi_ping_ffi_checksum_method_messagingclient_build_linking_ticket() != 21631 {
         return InitializationResult.apiChecksumMismatch
     }

package/ios/PingNativeModule.m

@@ -96,6 +96,16 @@ RCT_EXTERN_METHOD(addMembers: (NSArray *)conversationId
                   resolver: (RCTPromiseResolveBlock)resolve
                   rejecter: (RCTPromiseRejectBlock)reject)
 
+// Post-link reconciliation: admit a freshly-linked device to every chat in
+// `entries`. `entries` is an array of `{ conversationId: [Int], keyPackage: [Int] }`
+// dicts. Returns an array of `{ conversationId: [Int], status: String,
+// reason?: String, error?: String }`.
+RCT_EXTERN_METHOD(admitDeviceToChats: (NSArray *)newDeviceId
+                  entries: (NSArray *)entries
+                  nowMs: (double)nowMs
+                  resolver: (RCTPromiseResolveBlock)resolve
+                  rejecter: (RCTPromiseRejectBlock)reject)
+
 RCT_EXTERN_METHOD(removeMembers: (NSArray *)conversationId
                   leafIndexes: (NSArray *)leafIndexes
                   nowMs: (double)nowMs
@@ -136,6 +146,15 @@ RCT_EXTERN_METHOD(consumeLinkingTicket: (NSDictionary *)ticket
                   resolver: (RCTPromiseResolveBlock)resolve
                   rejecter: (RCTPromiseRejectBlock)reject)
 
+// [CR-3] HPKE-open a sealed LinkingTicket on the new device. Free
+// function (not on the client instance) — the new device is pre-init
+// and doesn't have a MessagingClient yet at the time of the open call.
+// Returns the same dict shape `consumeLinkingTicket` accepts as input.
+RCT_EXTERN_METHOD(openLinkingTicket: (NSArray *)sealed
+                  newDevicePriv: (NSArray *)newDevicePriv
+                  resolver: (RCTPromiseResolveBlock)resolve
+                  rejecter: (RCTPromiseRejectBlock)reject)
+
 RCT_EXTERN_METHOD(revokeDevice: (NSArray *)deviceId
                   nowMs: (double)nowMs
                   resolver: (RCTPromiseResolveBlock)resolve

package/ios/PingNativeModule.swift

@@ -439,6 +439,40 @@ public final class PingNative: RCTEventEmitter {
         }
     }
 
+    /// Admit a freshly-linked device to every chat in `entries`. Mirrors the SDK's
+    /// `MessagingClient.admit_device_to_chats` — one Commit + Welcome per chat,
+    /// per-chat outcomes returned so a single bad KP doesn't strand the user on
+    /// the other chats. `entries` is `{ conversationId: [Int], keyPackage: [Int] }[]`.
+    /// Result is `{ conversationId: [Int], status: "admitted"|"skipped"|"failed",
+    /// reason?: String, error?: String }[]`.
+    @objc(admitDeviceToChats:entries:nowMs:resolver:rejecter:)
+    public func admitDeviceToChatsNative(
+        _ newDeviceIdBytes: NSArray,
+        entries entriesArr: 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(newDeviceIdBytes)
+                let entries = try TypeBridge.decodeAdmitChatEntryArray(entriesArr)
+                let outcomes = try await client.admitDeviceToChats(
+                    newDeviceId: deviceId,
+                    entries: entries,
+                    nowMs: UInt64(nowMs)
+                )
+                resolve(TypeBridge.encodeAdmitChatOutcomeArray(outcomes))
+            } catch {
+                reject("AdmitDeviceToChatsFailed", 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:)
@@ -650,6 +684,31 @@ public final class PingNative: RCTEventEmitter {
         }
     }
 
+    /// HPKE-open a sealed `LinkingTicket` on the new device ([CR-3]).
+    /// Free function (not on `client`) — the new device is pre-init and
+    /// doesn't have a `MessagingClient` yet when the open happens. Mirrors
+    /// the wasm SDK's `MessagingClient.openLinkingTicket(sealed, priv)`
+    /// static so the desktop link host can decode the ticket before
+    /// calling `init` + `consumeLinkingTicket`.
+    @objc(openLinkingTicket:newDevicePriv:resolver:rejecter:)
+    public func openLinkingTicketNative(
+        _ sealedBytes: NSArray,
+        newDevicePriv newDevicePrivBytes: NSArray,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        do {
+            let sealed = try TypeBridge.decodeBytesOrThrow(sealedBytes, field: "sealed")
+            let priv = try TypeBridge.decodeBytesOrThrow(newDevicePrivBytes, field: "newDevicePriv")
+            // `open_linking_ticket` is a UniFFI top-level free function;
+            // Swift exposes it camelCased.
+            let ticket = try openLinkingTicket(sealed: sealed, newDevicePriv: priv)
+            resolve(TypeBridge.encodeLinkingTicket(ticket))
+        } catch {
+            reject("OpenLinkingFailed", String(describing: error), error)
+        }
+    }
+
     /// Revoke a device ([CR-2]). Returns the array of Commit envelopes the SDK
     /// produced — one per conversation the device was a locally-known leaf in.
     /// Empty array means the device wasn't locally known (scope limit per CR-2).

package/ios/TypeBridge.swift

@@ -318,6 +318,55 @@ enum TypeBridge {
         return try arr.map { try decodeKeyPackageEntry($0) }
     }
 
+    // MARK: - AdmitChat (post-link device admission)
+
+    /// Decode `{ conversationId: [Int], keyPackage: [Int] }` into UniFFI's
+    /// `AdmitChatEntry`. Used by `admitDeviceToChatsNative` — one entry per
+    /// chat the existing device is admitting the new device into.
+    static func decodeAdmitChatEntry(_ value: Any?) throws -> AdmitChatEntry {
+        guard let dict = value as? [String: Any] else {
+            throw BridgeError.decodeFailure("expected AdmitChatEntry dict")
+        }
+        let convId = try decodeConversationId(dict["conversationId"] ?? dict["conversation_id"])
+        let keyPackage = try decodeBytesOrThrow(
+            dict["keyPackage"] ?? dict["key_package"],
+            field: "keyPackage"
+        )
+        return AdmitChatEntry(conversationId: convId, keyPackage: keyPackage)
+    }
+
+    static func decodeAdmitChatEntryArray(_ value: Any?) throws -> [AdmitChatEntry] {
+        guard let arr = value as? [Any] else {
+            throw BridgeError.decodeFailure("expected AdmitChatEntry array")
+        }
+        return try arr.map { try decodeAdmitChatEntry($0) }
+    }
+
+    /// Encode an `AdmitChatStatus` as one of `"admitted" | "skipped" | "failed"`.
+    /// Matches the web SDK's `AdmitChatOutcome.status` discriminator so a host
+    /// app sharing logic across web/desktop can switch on a single string.
+    static func encodeAdmitChatStatus(_ status: AdmitChatStatus) -> String {
+        switch status {
+        case .admitted: return "admitted"
+        case .skipped:  return "skipped"
+        case .failed:   return "failed"
+        }
+    }
+
+    static func encodeAdmitChatOutcome(_ outcome: AdmitChatOutcome) -> [String: Any] {
+        var dict: [String: Any] = [
+            "conversationId": encodeConversationId(outcome.conversationId),
+            "status": encodeAdmitChatStatus(outcome.status),
+        ]
+        if let reason = outcome.reason { dict["reason"] = reason }
+        if let error = outcome.error  { dict["error"]  = error  }
+        return dict
+    }
+
+    static func encodeAdmitChatOutcomeArray(_ outcomes: [AdmitChatOutcome]) -> [[String: Any]] {
+        return outcomes.map(encodeAdmitChatOutcome)
+    }
+
     // MARK: - [CR-13] CatchupAppEvent
 
     /// Decode `{ conversationId: [Int], appEventBytes: [Int] }` into UniFFI's

package/ios/pingFFI.h

@@ -382,6 +382,11 @@ uint64_t uniffi_ping_ffi_fn_constructor_messagingclient_init(RustBuffer identity
 uint64_t uniffi_ping_ffi_fn_method_messagingclient_add_members(void*_Nonnull ptr, RustBuffer conversation_id, RustBuffer entries, uint64_t now_ms
 );
 #endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_PING_FFI_FN_METHOD_MESSAGINGCLIENT_ADMIT_DEVICE_TO_CHATS
+#define UNIFFI_FFIDEF_UNIFFI_PING_FFI_FN_METHOD_MESSAGINGCLIENT_ADMIT_DEVICE_TO_CHATS
+uint64_t uniffi_ping_ffi_fn_method_messagingclient_admit_device_to_chats(void*_Nonnull ptr, RustBuffer new_device_id, RustBuffer entries, uint64_t now_ms
+);
+#endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_PING_FFI_FN_METHOD_MESSAGINGCLIENT_BUILD_LINKING_TICKET
 #define UNIFFI_FFIDEF_UNIFFI_PING_FFI_FN_METHOD_MESSAGINGCLIENT_BUILD_LINKING_TICKET
 uint64_t uniffi_ping_ffi_fn_method_messagingclient_build_linking_ticket(void*_Nonnull ptr, RustBuffer new_device_id, RustBuffer new_device_kp, RustBuffer last_app_events, uint64_t now_ms
@@ -883,6 +888,12 @@ uint16_t uniffi_ping_ffi_checksum_method_messageobserver_on_conversation_updated
 #define UNIFFI_FFIDEF_UNIFFI_PING_FFI_CHECKSUM_METHOD_MESSAGINGCLIENT_ADD_MEMBERS
 uint16_t uniffi_ping_ffi_checksum_method_messagingclient_add_members(void
     
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_PING_FFI_CHECKSUM_METHOD_MESSAGINGCLIENT_ADMIT_DEVICE_TO_CHATS
+#define UNIFFI_FFIDEF_UNIFFI_PING_FFI_CHECKSUM_METHOD_MESSAGINGCLIENT_ADMIT_DEVICE_TO_CHATS
+uint16_t uniffi_ping_ffi_checksum_method_messagingclient_admit_device_to_chats(void
+    
 );
 #endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_PING_FFI_CHECKSUM_METHOD_MESSAGINGCLIENT_BUILD_LINKING_TICKET

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ping-openmls-sdk-react-native-macos",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "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",

package/src/MessagingClient.ts

@@ -70,6 +70,24 @@ export interface CatchupAppEvent {
   appEventBytes: Uint8Array;
 }
 
+/** One per-chat KP for `MessagingClient.admitDeviceToChats`. Hosts claim these
+ *  from the auth-layer's per-account KP pool after the newly-linked device's
+ *  bootstrap has uploaded its KP batch. */
+export interface AdmitChatEntry {
+  conversationId: Uint8Array;
+  keyPackage: Uint8Array;
+}
+
+/** Per-chat result returned by `MessagingClient.admitDeviceToChats`. */
+export interface AdmitChatOutcome {
+  conversationId: Uint8Array;
+  status: "admitted" | "skipped" | "failed";
+  /** Set when `status === "skipped"`. Diagnostic only. */
+  reason?: string;
+  /** Set when `status === "failed"`. The underlying MLS / transport error. */
+  error?: string;
+}
+
 /**
  * High-level facade over the native MessagingClient. Methods marshal arguments + return
  * values across the JS↔Swift bridge; the actual MLS work happens in Rust.
@@ -87,6 +105,14 @@ export class MessagingClient {
   private constructor(
     private readonly disconnectStorage: () => void,
     private readonly disconnectTransport: () => void,
+    /**
+     * Keep a reference to the host transport so post-link reconciliation
+     * can prime its Welcome-recipient map before the native SDK emits
+     * Welcomes. The bridge connection (above) is what forwards `send` /
+     * `fetchSince` / `discoverDevices` calls — we keep this around purely
+     * for the host-side primitives (e.g. `setNextWelcomeRecipients`).
+     */
+    private readonly transport: Transport,
   ) {}
 
   /**
@@ -122,7 +148,7 @@ export class MessagingClient {
       throw e;
     }
 
-    const client = new MessagingClient(disconnectStorage, disconnectTransport);
+    const client = new MessagingClient(disconnectStorage, disconnectTransport, cfg.transport);
 
     // Install the observer bridge so native can fire application-message and
     // conversation-updated events. Failure here is non-fatal — the client still works
@@ -347,6 +373,95 @@ export class MessagingClient {
     await NativePing.consumeLinkingTicket(encodeLinkingTicket(ticket), Date.now());
   }
 
+  /**
+   * [CR-3] HPKE-open a sealed linking ticket on the new device. Static —
+   * the new device hasn't initialised a `MessagingClient` yet at the
+   * time of the open call (it does `openLinkingTicket` first to extract
+   * the auth-layer fields, hands them to `/v1/auth/link-verify` to
+   * mint tokens, THEN `init`s and `consumeLinkingTicket`s).
+   *
+   * Mirrors the wasm SDK's `MessagingClient.openLinkingTicket` so the
+   * desktop link host can share code shape with the web link host.
+   *
+   * @param sealed - HPKE-sealed bytes from `getLinkingTicket(ticketId)`
+   *                 (the BE relays exactly what the existing device
+   *                 `sealLinkingTicket`'d).
+   * @param newDevicePriv - 32-byte X25519 private key the new device
+   *                        generated for this pairing session.
+   */
+  static async openLinkingTicket(
+    sealed: Uint8Array,
+    newDevicePriv: Uint8Array,
+  ): Promise<LinkingTicket> {
+    const raw = await NativePing.openLinkingTicket(
+      Array.from(sealed),
+      Array.from(newDevicePriv),
+    );
+    return decodeLinkingTicket(raw);
+  }
+
+  /**
+   * Admit a freshly-linked device to every chat in `entries` — one Commit +
+   * Welcome per chat, with per-chat outcomes. Host calls this AFTER
+   * `consumeLinkingTicket` on the new device side (and after the new device
+   * has uploaded its KeyPackage batch so the existing device can claim per-chat
+   * KPs).
+   *
+   * Welcome routing: this method primes the host transport's
+   * `setNextWelcomeRecipients` for each chat BEFORE the native call so the
+   * BE's `POST /v1/messages?recipient=` query param lands correctly. Hosts
+   * that implement Transport.setNextWelcomeRecipients (PingTransport on web
+   * and desktop both do) need no further coordination. Hosts that don't see
+   * a silent no-op — Welcomes will still send, but Welcome routing depends
+   * entirely on the transport's existing recipient priming.
+   */
+  async admitDeviceToChats(
+    newDeviceId: Uint8Array,
+    entries: AdmitChatEntry[],
+  ): Promise<AdmitChatOutcome[]> {
+    // Pre-prime the transport's recipient map for every entry. Each entry's
+    // Welcome will consume its own slot on send; pre-priming the whole batch
+    // is safe because chat ids are unique within `entries`. We tolerate
+    // hosts without `setNextWelcomeRecipients` (e.g. tests) by treating the
+    // missing method as a no-op.
+    if (this.transport.setNextWelcomeRecipients) {
+      for (const entry of entries) {
+        try {
+          await this.transport.setNextWelcomeRecipients(
+            entry.conversationId,
+            [newDeviceId],
+          );
+        } catch {
+          // Priming is best-effort; the per-chat send will surface a 400
+          // from the BE if it actually needed the recipient.
+        }
+      }
+    }
+
+    const raw = await NativePing.admitDeviceToChats(
+      Array.from(newDeviceId),
+      entries.map((e) => ({
+        conversationId: Array.from(e.conversationId),
+        keyPackage: Array.from(e.keyPackage),
+      })),
+      Date.now(),
+    );
+    return raw.map((o: {
+      conversationId: number[];
+      status: "admitted" | "skipped" | "failed";
+      reason?: string;
+      error?: string;
+    }) => {
+      const outcome: AdmitChatOutcome = {
+        conversationId: Uint8Array.from(o.conversationId),
+        status: o.status,
+      };
+      if (o.reason !== undefined) outcome.reason = o.reason;
+      if (o.error !== undefined) outcome.error = o.error;
+      return outcome;
+    });
+  }
+
   /**
    * Revoke a device ([CR-2]).
    *

package/src/NativePing.ts

@@ -117,6 +117,28 @@ export interface Spec extends TurboModule {
     nowMs: number,
   ): Promise<null>;
 
+  /**
+   * Admit a freshly-linked device to every chat in `entries`. The new device
+   * gets its own MLS leaf (so per-device PCS still works) and the BE-side
+   * `conversation_members` row is materialised as a side effect of each
+   * Welcome. Returns per-chat outcomes — `status` is one of `"admitted"`,
+   * `"skipped"`, `"failed"`. On `"failed"`, `error` carries the underlying
+   * MLS / transport error. On `"skipped"`, `reason` carries the diagnostic
+   * (e.g. `"device_group"` when a DG slipped into the entries).
+   */
+  admitDeviceToChats(
+    newDeviceId: number[],
+    entries: { conversationId: number[]; keyPackage: number[] }[],
+    nowMs: number,
+  ): Promise<
+    {
+      conversationId: number[];
+      status: "admitted" | "skipped" | "failed";
+      reason?: string;
+      error?: string;
+    }[]
+  >;
+
   /** Remove members by leaf index in the conversation's ratchet tree. */
   removeMembers(
     conversationId: number[],
@@ -178,6 +200,19 @@ export interface Spec extends TurboModule {
     nowMs: number,
   ): Promise<null>;
 
+  /**
+   * [CR-3] HPKE-open a sealed linking ticket on the new device. Free
+   * function — runs BEFORE `initClient` so the host can decode the
+   * ticket fields (`user_pubkey`, `new_device_id`, `device_binding_sig`)
+   * and submit them to the auth layer's `/v1/auth/link-verify` before
+   * spinning up the messaging client. Returns the same dict shape
+   * `consumeLinkingTicket` accepts.
+   */
+  openLinkingTicket(
+    sealed: number[],
+    newDevicePriv: number[],
+  ): Promise<Record<string, unknown>>;
+
   /**
    * Revoke a device ([CR-2]). Returns one Commit envelope per conversation the
    * device was a locally-known leaf in. Empty array means the device wasn't locally

package/src/transport-bridge.ts

@@ -26,6 +26,17 @@ export interface Transport {
    * handle.
    */
   subscribe?(onEvent: (envelopeJson: Record<string, unknown>) => void): { unsubscribe(): void };
+  /**
+   * Optional. Prime the host with recipient device ids for the NEXT Welcome on
+   * `conversationId`. Called by `MessagingClient.admitDeviceToChats` before
+   * each per-chat Welcome send so the BE's `POST /v1/messages?recipient=`
+   * query param lands correctly. Hosts that route Welcomes differently (or
+   * don't need per-recipient routing) may leave this unimplemented.
+   */
+  setNextWelcomeRecipients?(
+    conversationId: Uint8Array,
+    recipientDeviceIds: Uint8Array[],
+  ): Promise<void>;
 }
 
 interface TransportCallEvent {