Merge branch 'main' into fix-search-import

Author: jhaaaa

docs/pages/chat-apps/list-stream-sync/sync-preferences.mdx

@@ -130,7 +130,7 @@ Now, let's describe how the preferences sync worker helps keep user consent pref
 
 Preferences sync handles HMAC keys in the same way.
 
-For example, it will handle syncing an HMAC key shared by Installation B to other installations. When Installation A and C call `preferences.sync` or `syncAll`, the sync worker gets Installation B's HMAC key message from the preferences group and ensures that Installation A and C get the HMAC key for Installation B.
+For example, when a new installation generates a root HMAC key and publishes it to the sync group, other installations will eventually replace their root HMAC keys with the last one posted. When Installation A and C call `preferences.sync` or `syncAll`, the sync worker gets the latest root HMAC key message from the preferences group and ensures that all installations converge to use the same root HMAC key. This root key is then used to derive group-specific HMAC keys for each conversation.
 
 ## Sync preferences
 

docs/pages/chat-apps/push-notifs/understand-push-notifs.mdx

@@ -97,9 +97,24 @@ There are some nuances to how push notifications can be handled once received by
 
 XMTP uses Hash-based Message Authentication Code (HMAC) keys for push notifications. A user holds the HMAC keys for any conversation they join, but an outside observer only sees the keys without knowing who owns them. For instance, suppose Alix has HMAC key #1, and we also see HMAC keys #2 and #3. If Alix discloses that they hold key #1, then we know key #1 belongs to them. However, we have no way of knowing who holds keys #2 or #3 unless those individuals reveal that information. This design preserves privacy while enabling secure communication.
 
-The HMAC key is derived from a generated root HMAC key, the message's group ID, and the number of 30-day periods since the Unix epoch, along with some salt. Anytime a user gets a new installation, they get new HMAC keys for it. In this case, how do the user's older installations learn about the user's new installation HMAC key so they can properly decrypt and route certain messages and push notifications for that newly added installation?
+### HMAC key generation and syncing
 
-This is one of the jobs of the [history sync](/chat-apps/list-stream-sync/history-sync) feature. It listens for `preferences.streamAllPreferenceUpdates()`, which are user preferences that may include an enum with HMAC keys for new installations. When a user's new installation publishes updated HMAC info, older installations can see that update and must [resubscribe to topics](/chat-apps/push-notifs/push-notifs#resubscribe-to-topics-to-get-new-hmac-keys) to get the new HMAC keys.
+XMTP uses a two-level HMAC key system:
+
+1. **Root HMAC key**: Each inbox has a root HMAC key that serves as the foundation for deriving group-specific keys
+2. **Group HMAC keys**: Each conversation group has its own HMAC key, derived from the root HMAC key, the message's group ID, and the number of 30-day periods since the Unix epoch, along with some salt. XMTP generates one HMAC key per group, not per installation.
+
+#### Root HMAC key syncing across installations
+
+When a new installation for an inbox is created, it generates a new root HMAC key and publishes it to the sync group. Other installations of the same inbox will eventually replace their root HMAC keys with the last one posted in the sync group. This means the root HMAC key eventually becomes the same across all installations for a given inbox.
+
+#### Effects of stale root HMAC keys
+
+The only side effect of having a stale root HMAC key is that a user might receive push notifications for their own messages. This happens because the push server uses group HMAC keys (derived from the root key) to filter out a user's own messages. When the derived group keys don't match due to having a stale root key, the server can't identify that the user sent the message and sends them a notification.
+
+#### How installations learn about new root HMAC keys
+
+This is one of the jobs of the [history sync](/chat-apps/list-stream-sync/history-sync) feature. It listens for `preferences.streamAllPreferenceUpdates()`, which are user preferences that may include an enum with root HMAC keys for new installations. When a user's new installation publishes updated root HMAC key info, older installations can see that update and must [resubscribe to topics](/chat-apps/push-notifs/push-notifs#resubscribe-to-topics-to-get-new-hmac-keys) to get the new group HMAC keys derived from the updated root key.
 
 ## Understand DM stitching and push notifications
 

llms/llms-full.txt

@@ -1,6 +1,6 @@
 # XMTP Full Documentation
 
-Generated at 07:38 PM UTC / September 17, 2025
+Generated at 11:44 PM UTC / September 19, 2025
 
 ## Instructions for AI Tools
 
@@ -3985,7 +3985,7 @@ Now, let's describe how the preferences sync worker helps keep user consent pref
 
 Preferences sync handles HMAC keys in the same way.
 
-For example, it will handle syncing an HMAC key shared by Installation B to other installations. When Installation A and C call `preferences.sync` or `syncAll`, the sync worker gets Installation B's HMAC key message from the preferences group and ensures that Installation A and C get the HMAC key for Installation B.
+For example, when a new installation generates a root HMAC key and publishes it to the sync group, other installations will eventually replace their root HMAC keys with the last one posted. When Installation A and C call `preferences.sync` or `syncAll`, the sync worker gets the latest root HMAC key message from the preferences group and ensures that all installations converge to use the same root HMAC key. This root key is then used to derive group-specific HMAC keys for each conversation.
 
 ## Sync preferences
 
@@ -5104,9 +5104,24 @@ There are some nuances to how push notifications can be handled once received by
 
 XMTP uses Hash-based Message Authentication Code (HMAC) keys for push notifications. A user holds the HMAC keys for any conversation they join, but an outside observer only sees the keys without knowing who owns them. For instance, suppose Alix has HMAC key #1, and we also see HMAC keys #2 and #3. If Alix discloses that they hold key #1, then we know key #1 belongs to them. However, we have no way of knowing who holds keys #2 or #3 unless those individuals reveal that information. This design preserves privacy while enabling secure communication.
 
-The HMAC key is derived from a generated root HMAC key, the message's group ID, and the number of 30-day periods since the Unix epoch, along with some salt. Anytime a user gets a new installation, they get new HMAC keys for it. In this case, how do the user's older installations learn about the user's new installation HMAC key so they can properly decrypt and route certain messages and push notifications for that newly added installation?
+### HMAC key generation and syncing
 
-This is one of the jobs of the [history sync](/chat-apps/list-stream-sync/history-sync) feature. It listens for `preferences.streamAllPreferenceUpdates()`, which are user preferences that may include an enum with HMAC keys for new installations. When a user's new installation publishes updated HMAC info, older installations can see that update and must [resubscribe to topics](/chat-apps/push-notifs/push-notifs#resubscribe-to-topics-to-get-new-hmac-keys) to get the new HMAC keys.
+XMTP uses a two-level HMAC key system:
+
+1. **Root HMAC key**: Each inbox has a root HMAC key that serves as the foundation for deriving group-specific keys
+2. **Group HMAC keys**: Each conversation group has its own HMAC key, derived from the root HMAC key, the message's group ID, and the number of 30-day periods since the Unix epoch, along with some salt. XMTP generates one HMAC key per group, not per installation.
+
+#### Root HMAC key syncing across installations
+
+When a new installation for an inbox is created, it generates a new root HMAC key and publishes it to the sync group. Other installations of the same inbox will eventually replace their root HMAC keys with the last one posted in the sync group. This means the root HMAC key eventually becomes the same across all installations for a given inbox.
+
+#### Effects of stale root HMAC keys
+
+The only side effect of having a stale root HMAC key is that a user might receive push notifications for their own messages. This happens because the push server uses group HMAC keys (derived from the root key) to filter out a user's own messages. When the derived group keys don't match due to having a stale root key, the server can't identify that the user sent the message and sends them a notification.
+
+#### How installations learn about new root HMAC keys
+
+This is one of the jobs of the [history sync](/chat-apps/list-stream-sync/history-sync) feature. It listens for `preferences.streamAllPreferenceUpdates()`, which are user preferences that may include an enum with root HMAC keys for new installations. When a user's new installation publishes updated root HMAC key info, older installations can see that update and must [resubscribe to topics](/chat-apps/push-notifs/push-notifs#resubscribe-to-topics-to-get-new-hmac-keys) to get the new group HMAC keys derived from the updated root key.
 
 ## Understand DM stitching and push notifications