From 531f1a43becc9f8669f25740e6f296401a58da2e Mon Sep 17 00:00:00 2001 From: shum Date: Thu, 21 Aug 2025 07:17:56 +0000 Subject: [PATCH] docs/ios-notifications: add new diagram --- docs/protocol/diagrams/ios-notifications.mmd | 90 ++++++++++++++++++++ docs/protocol/diagrams/ios-notifications.svg | 1 + docs/protocol/simplex-chat.md | 4 + 3 files changed, 95 insertions(+) create mode 100644 docs/protocol/diagrams/ios-notifications.mmd create mode 100644 docs/protocol/diagrams/ios-notifications.svg diff --git a/docs/protocol/diagrams/ios-notifications.mmd b/docs/protocol/diagrams/ios-notifications.mmd new file mode 100644 index 0000000000..aede1d3e3e --- /dev/null +++ b/docs/protocol/diagrams/ios-notifications.mmd @@ -0,0 +1,90 @@ +--- +title: "Notifications flow" +--- + +sequenceDiagram + participant Client + participant NTF + participant SMP + participant Apple + + autonumber + + Note over Client,NTF: iOS setup app first-time + + Client->>NTF:Create token (tknCreated) + NTF->>Apple:Send test notification with secret to APNs + Apple-->>Client:Send test notification with secret to client + Client->>NTF:Verify iOS token (tknVerified) + + Note over Client,NTF: iOS creates link + + alt Create credentials for queue (new client) + Client->>SMP:ntfNewCreated + else Create credentials for queue (old client) + Client->>SMP:ntfCreated + end + + Note over Client,SMP: Subscription phase + + Client->>NTF:Create subscription based on credentials (subCreated) + + alt Subscription request + NTF->>SMP:ntfSub + else Subscription fail: AUTH + NTF->>SMP:ntfSubAuth + else Subscription fail: Duplicate + NTF->>SMP:ntfSubDuplicate + end + + Note over Client,SMP: Notification phase + + loop Every minute + SMP-->SMP: Queues with notification
waiting to be delivered (ntfCount1) + end + + alt SMP recevies
message with notification + SMP->>SMP:msgRecvNtf + else Client asks SMP to get new message + Client->>SMP:msgGet + else Client sents message with notification flag + Client->>SMP:msgSentNtf + end + + alt SMP recevies get + SMP-->>SMP:msgRecvGet + else Prohibited + SMP-->>SMP:msgGetProhibited + else Duplicate + SMP-->SMP:msgGetDuplicate + else AUTH + SMP-->SMP:msgGetAuth + else NoMsg + SMP-->SMP:msgGetNoMsg + end + + alt Send notification + SMP->>NTF:msgNtfs + else No subsciptions
(will deliver) + SMP->>SMP:msgNtfNoSub + else Lost
(no delivery) + SMP->>SMP:msgNtfLost + else Expired
(no delivery) + SMP->>SMP:msgNtfExpired + end + + NTF-->>NTF:Received notification (ntfReceived) + + Note over Client,Apple: Final phase + + alt Delivered notification to Apple APNs + NTF-->>Apple:ntfDelivered + else Failed to deliver + NTF-->>Apple:ntfFailed + end + + Apple->>Client:Sent notification (visible only via Apple's Console) + + Note over Client,SMP: Confirmation phase + + Client-->>SMP:Client received (msgRecvNtf) diff --git a/docs/protocol/diagrams/ios-notifications.svg b/docs/protocol/diagrams/ios-notifications.svg new file mode 100644 index 0000000000..4aa76c3c34 --- /dev/null +++ b/docs/protocol/diagrams/ios-notifications.svg @@ -0,0 +1 @@ +AppleSMPNTFClientAppleSMPNTFClientiOS setup app first-timeiOS creates linkalt[Create credentials for queue (new client)][Create credentials for queue (old client)]Subscription phasealt[Subscriptionrequest][Subscription fail:AUTH][Subscription fail:Duplicate]Notification phaseloop[Every minute]alt[SMP receviesmessage with notification][Client asks SMP to get new message][Client sents message with notification flag]alt[SMPreceviesget][Prohibited-][Duplicate][AUTH][NoMsg]alt[Sendnotification-][No subsciptions(will deliver)][Lost(no delivery)][Expired(no delivery)]Final phasealt[Delivered notification to Apple APNs][Failed to deliver]Confirmation phaseCreate token (tknCreated)1Send test notification with secret to APNs2Send test notification with secret to client3Verify iOS token (tknVerified)4ntfNewCreated5ntfCreated6Create subscription based on credentials (subCreated)7ntfSub8ntfSubAuth9ntfSubDuplicate10Queues with notificationwaiting to be delivered (ntfCount1)11msgRecvNtf12msgGet13msgSentNtf14msgRecvGet15msgGetProhibited16msgGetDuplicate17msgGetAuth18msgGetNoMsg19msgNtfs20msgNtfNoSub21msgNtfLost22msgNtfExpired23Received notification (ntfReceived)24ntfDelivered25ntfFailed26Sent notification (visible only via Apple's Console)27Client received (msgRecvNtf)28Notifications flow \ No newline at end of file diff --git a/docs/protocol/simplex-chat.md b/docs/protocol/simplex-chat.md index c74465f6fe..45b75efd52 100644 --- a/docs/protocol/simplex-chat.md +++ b/docs/protocol/simplex-chat.md @@ -342,3 +342,7 @@ This threat model compliments SMP, XFTP, push notifications and XRCP protocols t *cannot:* - prove that two group members with incognito profiles is the same user. + +## Sub-protocol for push notifications + +![iOS notifications](./diagrams/ios-notifications.svg)