Handle pairing join requests in the Notification Service Extension (#984)

A pairing join request now reaches the user even when the app isn't
running: the NSE detects PairingJoinRequestContent in both push paths
(the welcome push that delivers the brand-new pairing DM, and encrypted
message pushes for resends), verifies the slug against this device's own
identity key, and shows "<device> is requesting to pair". The verified
request is stashed in app-group defaults (PendingPairRequestStore) and
the app presents the initiator PIN sheet from the stash on its next
activation; the stash doubles as the NSE's dedupe record against the
joiner's 5s resend cadence.

Verification logic is extracted into PairingJoinRequestDetector, shared
with the main stream's fast path, with a pure core covered by unit tests
(self-signed slug accepted; foreign-key, expired, self-sender, wrong
inbox, and garbage slugs rejected).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: yewreeka

Convos/Conversations List/ConversationsViewModel.swift

@@ -1036,6 +1036,15 @@ extension ConversationsViewModel {
 
     private func presentIncomingPairingSheet(joinerInboxId: String, deviceName: String) {
         QAEvent.emit(.pairing, "incoming_request_surfaced", ["joinerInboxId": joinerInboxId])
+        // The NSE stashes for pushes that arrive while the app is
+        // foregrounded too; presenting from the stream path must discard
+        // that stash (and any delivered banners), or the next activation
+        // would re-present a ghost PIN sheet for an already-handled
+        // request.
+        _ = PendingPairRequestStore.consumePending(
+            appGroup: ConfigManager.shared.currentEnvironment.appGroupIdentifier
+        )
+        removeDeliveredPairingNotifications()
         incomingPairingPresentedAt = Date()
         incomingPairingRequest = PairingSheetViewModel(
             pairingService: DeferredInitiatorPairingService(session: session),
@@ -1045,24 +1054,60 @@ extension ConversationsViewModel {
     }
 
     private func presentPendingIncomingPairRequestIfNeeded() {
-        guard let pending = pendingIncomingPairRequest else { return }
-        pendingIncomingPairRequest = nil
-        UNUserNotificationCenter.current().removeDeliveredNotifications(
-            withIdentifiers: [Constant.incomingPairingNotificationId]
-        )
+        // Bail before consuming anything when a pairing flow is already
+        // on screen: a second initiator coordinator would race PIN
+        // generation for the same joiner. Consuming first and bailing
+        // after would destructively drop the stash (the app-group read
+        // removes it), losing the request if the joiner has stopped
+        // re-sending (killed/backgrounded). Leave it stashed so the next
+        // activation, once the active flow ends, can present it.
+        guard PairingSheetViewModel.active == nil, incomingPairingRequest == nil else { return }
+        // Two stash sources: in-memory (request arrived while this
+        // process was backgrounded) and the app-group store written by
+        // the NSE (request arrived while the app wasn't running at all).
+        var pending: PendingIncomingPairRequest?
+        if let inMemory = pendingIncomingPairRequest {
+            pendingIncomingPairRequest = nil
+            pending = inMemory
+        } else if let stashed = PendingPairRequestStore.consumePending(
+            appGroup: ConfigManager.shared.currentEnvironment.appGroupIdentifier
+        ) {
+            pending = PendingIncomingPairRequest(
+                joinerInboxId: stashed.joinerInboxId,
+                deviceName: stashed.deviceName,
+                receivedAt: stashed.receivedAt
+            )
+        }
+        guard let pending else { return }
+        removeDeliveredPairingNotifications()
         // The joiner re-sends its request for the length of the pairing
         // window; past that the handshake would just expire on send, so
         // stale stashes are dropped instead of surfaced.
         guard Date().timeIntervalSince(pending.receivedAt) < Constant.foundDevicePairingWindow else { return }
-        guard PairingSheetViewModel.active == nil, incomingPairingRequest == nil else { return }
         presentIncomingPairingSheet(joinerInboxId: pending.joinerInboxId, deviceName: pending.deviceName)
     }
 
+    /// Removes every delivered "is requesting to pair" banner: the app's
+    /// own local one (fixed request identifier) and any the NSE produced
+    /// for remote pushes, whose request identifiers are system-assigned
+    /// and only findable via the shared pairing thread identifier.
+    private func removeDeliveredPairingNotifications() {
+        let center = UNUserNotificationCenter.current()
+        center.getDeliveredNotifications { notifications in
+            let pairingIds = notifications
+                .filter { $0.request.content.threadIdentifier == PairingNotificationThread.identifier }
+                .map(\.request.identifier)
+            let ids = pairingIds + [Constant.incomingPairingNotificationId]
+            center.removeDeliveredNotifications(withIdentifiers: ids)
+        }
+    }
+
     private func scheduleIncomingPairingNotification(deviceName: String) {
         let content = UNMutableNotificationContent()
         content.title = "Pair new device"
         content.body = "\"\(deviceName)\" is requesting to pair"
         content.sound = .default
+        content.threadIdentifier = PairingNotificationThread.identifier
         let request = UNNotificationRequest(
             identifier: Constant.incomingPairingNotificationId,
             content: content,
@@ -1086,11 +1131,18 @@ extension ConversationsViewModel {
         pendingPairDevice = nil
     }
 
-    /// Sheet-dismissal hook for the auto-surfaced initiator flow.
+    /// Sheet-dismissal hook for the auto-surfaced initiator flow. Also
+    /// discards any stash the NSE wrote for resends that landed while
+    /// the sheet was up - the request was handled either way, and a
+    /// leftover stash would re-present a ghost sheet on next activation.
     func dismissIncomingPairingRequest() {
         incomingPairingRequest?.triggerCancel()
         incomingPairingRequest = nil
         incomingPairingPresentedAt = nil
+        _ = PendingPairRequestStore.consumePending(
+            appGroup: ConfigManager.shared.currentEnvironment.appGroupIdentifier
+        )
+        removeDeliveredPairingNotifications()
     }
 
     private enum Constant {

ConvosCore/Sources/ConvosCore/Inboxes/MessagingService+PushNotifications.swift

@@ -133,6 +133,14 @@ extension MessagingService {
         // Sync all conversations - this will fetch any groups we've been added to
         _ = try await client.conversationsProvider.syncAllConversations(consentStates: [.unknown])
 
+        // The pairing DM is a brand-new conversation, so a pairing join
+        // request's first delivery is this welcome push. Detect it before
+        // anything else can return - the joiner only waits a few minutes,
+        // and with no topic subscription for the new DM there may be no
+        // second push. Detection has no side effects; the invite
+        // processing below still runs either way.
+        let pairingRequest = await detectRecentPairingJoinRequest(client: client)
+
         // Case 1: Process join requests (others accepting our invites)
         let joinRequestOutcomes = await joinRequestsManager.processJoinRequestOutcomes(since: lastProcessed, client: client)
         await handleJoinRequestOutcomesForPush(
@@ -142,6 +150,19 @@ extension MessagingService {
             context: "welcome"
         )
 
+        if let pairingRequest {
+            // Only let a genuinely surfaced pairing request short-circuit.
+            // The scan spans all recent DMs, not just this push's topic, so
+            // a deduped duplicate (.droppedMessage) might belong to an
+            // earlier push - returning it here would suppress a join-result
+            // or new-group notification this same push legitimately carries.
+            // On a duplicate, fall through to those checks instead.
+            let notification = pairingRequestNotification(pairingRequest, userInfo: userInfo)
+            if !notification.isDroppedMessage {
+                return notification
+            }
+        }
+
         if let result = joinRequestOutcomes.compactMap(\.result).first {
             setLastWelcomeProcessed(processTime, for: client.inboxId)
 
@@ -335,6 +356,14 @@ extension MessagingService {
                 return .droppedMessage
             }
 
+            // A pairing join request (the joiner re-sends every few
+            // seconds while connecting) - surface "<device> is requesting
+            // to pair" instead of feeding it to the invite flow.
+            if let identity = try? identityStore.loadSync(),
+               let pairingRequest = PairingJoinRequestDetector.verifiedJoinRequest(in: decodedMessage, identity: identity) {
+                return pairingRequestNotification(pairingRequest, userInfo: userInfo)
+            }
+
             // DMs are only used for join requests (invite acceptance flow)
             // When someone accepts an invite, they send the signed invite back via DM
             // This allows us to add them to the group conversation they were invited to
@@ -1249,3 +1278,93 @@ extension MessagingService {
         }
     }
 }
+
+// MARK: - Pairing Join Requests
+
+extension MessagingService {
+    /// Scans recently created unknown-consent DMs for a verified pairing
+    /// join request (see `PairingJoinRequestDetector` for the security
+    /// model). Used by the welcome-push path, where the request's content
+    /// isn't in the payload - the pairing DM was just synced from the
+    /// network. Bounded to a handful of fresh DMs and their latest
+    /// messages so it stays cheap inside the NSE's time budget.
+    func detectRecentPairingJoinRequest(client: any XMTPClientProvider) async -> VerifiedPairingJoinRequest? {
+        guard let identity = try? identityStore.loadSync() else { return nil }
+        let cutoff = Date().addingTimeInterval(-PairingPushConstant.requestWindow)
+        let cutoffNs = Int64(cutoff.timeIntervalSince1970 * 1_000_000_000)
+        let dms: [Dm]
+        do {
+            dms = try client.conversationsProvider.listDms(
+                createdAfterNs: cutoffNs,
+                createdBeforeNs: nil,
+                lastActivityBeforeNs: nil,
+                lastActivityAfterNs: nil,
+                limit: PairingPushConstant.maxScannedDms,
+                consentStates: [.unknown],
+                orderBy: .createdAt
+            )
+        } catch {
+            Log.warning("NSE: failed to list DMs for pairing scan: \(error)")
+            return nil
+        }
+        for dm in dms {
+            let messages = (try? await dm.messages(limit: PairingPushConstant.maxScannedMessagesPerDm)) ?? []
+            for message in messages {
+                if let request = PairingJoinRequestDetector.verifiedJoinRequest(in: message, identity: identity) {
+                    return request
+                }
+            }
+        }
+        return nil
+    }
+
+    /// Builds the "<device> is requesting to pair" notification and
+    /// stashes the request for the main app to present on next activation
+    /// (`PendingPairRequestStore`). The stash doubles as the dedupe
+    /// record: the joiner re-sends its request every few seconds, and one
+    /// banner per burst is plenty.
+    func pairingRequestNotification(
+        _ request: VerifiedPairingJoinRequest,
+        userInfo: [AnyHashable: Any]
+    ) -> DecodedNotificationContent {
+        let appGroup = environment.appGroupIdentifier
+        if let existing = PendingPairRequestStore.pending(appGroup: appGroup),
+           existing.joinerInboxId == request.joinerInboxId,
+           Date().timeIntervalSince(existing.receivedAt) < PairingPushConstant.dedupeWindow {
+            Log.debug("NSE: suppressing duplicate pairing request notification")
+            return .droppedMessage
+        }
+        PendingPairRequestStore.setPending(
+            .init(
+                joinerInboxId: request.joinerInboxId,
+                deviceName: request.deviceName,
+                receivedAt: Date()
+            ),
+            appGroup: appGroup
+        )
+        Log.info("NSE: surfacing pairing join request from \(request.joinerInboxId)")
+        // The conversationId becomes the notification's threadIdentifier.
+        // Stamping the fixed pairing thread lets the system collapse a
+        // resend burst's banners and lets the app's activation cleanup
+        // find and remove NSE-posted ones (whose request identifiers are
+        // system-assigned and unknowable here).
+        return .init(
+            title: "Pair new device",
+            body: "\"\(request.deviceName)\" is requesting to pair",
+            conversationId: PairingNotificationThread.identifier,
+            userInfo: userInfo
+        )
+    }
+
+    private enum PairingPushConstant {
+        /// How far back a DM can have been created and still be scanned;
+        /// matches the joiner's resend window.
+        static let requestWindow: TimeInterval = 300
+        /// One banner per request burst: the joiner re-sends every ~5s,
+        /// and each NSE invocation is a fresh process, so dedupe lives in
+        /// the app-group stash rather than memory.
+        static let dedupeWindow: TimeInterval = 60
+        static let maxScannedDms: Int = 10
+        static let maxScannedMessagesPerDm: Int = 5
+    }
+}

ConvosCore/Sources/ConvosCore/Pairing/PairingJoinRequestDetector.swift

@@ -0,0 +1,67 @@
+import Foundation
+@preconcurrency import XMTPiOS
+
+/// A pairing join request that passed self-signature verification.
+public struct VerifiedPairingJoinRequest: Sendable, Equatable {
+    public let joinerInboxId: String
+    public let deviceName: String
+    public let slug: String
+
+    public init(joinerInboxId: String, deviceName: String, slug: String) {
+        self.joinerInboxId = joinerInboxId
+        self.deviceName = deviceName
+        self.slug = slug
+    }
+}
+
+/// Shared verification for pairing join requests that arrive outside an
+/// active pairing session - on the main message stream (`StreamProcessor`)
+/// or in a push notification (the NSE's welcome and message paths).
+///
+/// Only requests whose embedded invite slug is signed by this inbox's own
+/// identity key are surfaced: the iCloud-discovery joiner mints its slug
+/// from the synced keychain backup and the QR flow signs its slug locally,
+/// so both carry our signature, while a forged request can't - producing a
+/// valid slug requires the private key. The address comparison anchors
+/// that verification to our key: the slug's inboxId and address fields are
+/// attacker-choosable, but the signature only ever recovers to the
+/// signer's own address.
+public enum PairingJoinRequestDetector {
+    /// Returns the verified join request carried by `message`, or nil when
+    /// the message isn't a pairing join request or fails verification.
+    /// Decodes via the codec directly so it works on clients that never
+    /// registered the pairing codecs (the NSE's).
+    public static func verifiedJoinRequest(
+        in message: DecodedMessage,
+        identity: KeychainIdentity
+    ) -> VerifiedPairingJoinRequest? {
+        guard let typeId = try? message.encodedContent.type.typeID,
+              typeId == ContentTypePairingJoinRequest.typeID,
+              let content = try? PairingJoinRequestCodec().decode(content: message.encodedContent) else {
+            return nil
+        }
+        guard verify(slug: content.slug, senderInboxId: message.senderInboxId, identity: identity) else {
+            return nil
+        }
+        return VerifiedPairingJoinRequest(
+            joinerInboxId: message.senderInboxId,
+            deviceName: content.deviceName,
+            slug: content.slug
+        )
+    }
+
+    /// Pure verification core, separated from `DecodedMessage` extraction
+    /// so it can be unit tested with minted slugs. True when `slug` is a
+    /// valid, unexpired invite signed by `identity`'s own key and the
+    /// sender isn't this inbox itself.
+    public static func verify(
+        slug: String,
+        senderInboxId: String,
+        identity: KeychainIdentity
+    ) -> Bool {
+        guard senderInboxId != identity.inboxId else { return false }
+        guard let invite = try? PairingInvite.fromURLSafeSlug(slug) else { return false }
+        return invite.initiatorInboxId == identity.inboxId
+            && invite.initiatorAddress.lowercased() == identity.keys.privateKey.walletAddress.lowercased()
+    }
+}

ConvosCore/Sources/ConvosCore/Pairing/PendingPairRequestStore.swift

@@ -0,0 +1,79 @@
+import Foundation
+
+/// Hands a verified pairing join request from the Notification Service
+/// Extension to the main app. The NSE can't present the pairing sheet, so
+/// it stashes the request here (and shows a "<device> is requesting to
+/// pair" banner); the app consumes the stash on its next activation and
+/// presents the initiator flow. Also acts as the NSE's notification
+/// dedupe: the joiner re-sends its request every few seconds, and one
+/// banner per request burst is plenty.
+///
+/// Storage is app-group UserDefaults so both processes see it, mirroring
+/// `PairedDeviceNameStore`. UserDefaults is process-safe.
+public enum PendingPairRequestStore {
+    /// Display metadata only - deliberately no invite slug. A valid
+    /// unexpired slug is a bearer credential (it passes
+    /// `PairingJoinRequestDetector.verify` from any inbox), and the
+    /// app-group plist is plaintext and included in device backups; the
+    /// consumer only needs the joiner identity and a name to present
+    /// the PIN sheet.
+    public struct Pending: Codable, Sendable, Equatable {
+        public let joinerInboxId: String
+        public let deviceName: String
+        public let receivedAt: Date
+
+        public init(joinerInboxId: String, deviceName: String, receivedAt: Date) {
+            self.joinerInboxId = joinerInboxId
+            self.deviceName = deviceName
+            self.receivedAt = receivedAt
+        }
+    }
+
+    private static let pendingKey: String = "convos.pairing.pendingJoinRequest.v1"
+
+    private static func defaults(for appGroup: String) -> UserDefaults {
+        guard let suite = UserDefaults(suiteName: appGroup) else {
+            // Falling back means the NSE and the app each write their own
+            // standard defaults and the handoff silently never happens -
+            // make that observable.
+            Log.warning("PendingPairRequestStore: app-group suite unavailable, falling back to standard defaults")
+            return .standard
+        }
+        return suite
+    }
+
+    /// Stashes the request, replacing any previous one.
+    public static func setPending(_ pending: Pending, appGroup: String) {
+        guard let data = try? JSONEncoder().encode(pending) else { return }
+        defaults(for: appGroup).set(data, forKey: pendingKey)
+    }
+
+    /// Reads without clearing. The NSE uses this for dedupe decisions.
+    public static func pending(appGroup: String) -> Pending? {
+        guard let data = defaults(for: appGroup).data(forKey: pendingKey) else { return nil }
+        return try? JSONDecoder().decode(Pending.self, from: data)
+    }
+
+    /// Reads and clears. The app calls this on activation, and also when
+    /// the stream path presents a request directly - the NSE stashes for
+    /// pushes that arrive while the app is foregrounded too, and a stash
+    /// left behind after the flow was handled would re-present a ghost
+    /// PIN sheet on the next activation.
+    public static func consumePending(appGroup: String) -> Pending? {
+        let defs = defaults(for: appGroup)
+        guard let data = defs.data(forKey: pendingKey) else { return nil }
+        defs.removeObject(forKey: pendingKey)
+        return try? JSONDecoder().decode(Pending.self, from: data)
+    }
+}
+
+/// Thread identifier stamped on every "is requesting to pair"
+/// notification - the NSE's remote ones (via
+/// `DecodedNotificationContent.conversationId`, which the extension maps
+/// to `threadIdentifier`) and the app's local one - so the system
+/// collapses a resend burst into one thread and the app's activation
+/// cleanup can remove NSE-posted banners whose request identifiers are
+/// system-assigned.
+public enum PairingNotificationThread {
+    public static let identifier: String = "incoming-pairing-request"
+}