feat: harvest LID mappings from GetUserDevices usync response

.github/CONTRIBUTING.md

@@ -0,0 +1 @@
+See <https://docs.mau.fi/bridges/general/contributing.html>

.github/pull_request_template.md

@@ -0,0 +1,3 @@
+### Checklist
+
+* [ ] I have read and followed the contributing guidelines at <https://docs.mau.fi/bridges/general/contributing.html>

appstate.go

@@ -83,7 +83,6 @@ func (cli *Client) fetchAppState(ctx context.Context, name appstate.WAPatchName,
 		hasMore = patches.HasMorePatches
 		state, err = cli.applyAppStatePatches(ctx, name, state, patches, fullSync, eventsToDispatchPtr)
 		if err != nil {
-			cli.dispatchEvent(&events.AppStateSyncError{Name: name, FullSync: fullSync, Error: err})
 			return nil, err
 		}
 	}
@@ -161,6 +160,8 @@ func (cli *Client) applyAppStatePatches(
 	if err != nil {
 		if errors.Is(err, appstate.ErrKeyNotFound) {
 			go cli.requestMissingAppStateKeys(context.WithoutCancel(ctx), patches)
+		} else {
+			cli.dispatchEvent(&events.AppStateSyncError{Name: name, FullSync: fullSync, Error: err})
 		}
 		return state, fmt.Errorf("failed to decode app state %s patches: %w", name, err)
 	}
@@ -234,6 +235,19 @@ func (cli *Client) dispatchAppState(ctx context.Context, name appstate.WAPatchNa
 	}
 	logEvt.Msg("Received app state mutation")
 
+	if len(mutation.Index) == 1 && mutation.Index[0] == appstate.IndexNCTSaltSync {
+		var err error
+		if mutation.Operation == waServerSync.SyncdMutation_SET {
+			err = cli.storeNCTSalt(ctx, mutation.Action.GetNctSaltSyncAction().GetSalt())
+		} else if mutation.Operation == waServerSync.SyncdMutation_REMOVE {
+			err = cli.clearNCTSalt(ctx)
+		}
+		if err != nil {
+			cli.Log.Warnf("Failed to update NCT salt from app state mutation: %v", err)
+		}
+		return
+	}
+
 	if mutation.Operation != waServerSync.SyncdMutation_SET {
 		return
 	}

appstate/decode.go

@@ -9,6 +9,7 @@ package appstate
 import (
 	"bytes"
 	"context"
+	"crypto/hmac"
 	"crypto/sha256"
 	"encoding/json"
 	"fmt"
@@ -122,7 +123,7 @@ func (out *patchOutput) RemoveMAC(indexMAC []byte) {
 	out.RemovedMACs = append(out.RemovedMACs, indexMAC)
 	// If the mutation was previously added in this patch, remove it from AddedMACs
 	out.AddedMACs = slices.DeleteFunc(out.AddedMACs, func(mac store.AppStateMutationMAC) bool {
-		return bytes.Equal(mac.IndexMAC, indexMAC)
+		return hmac.Equal(mac.IndexMAC, indexMAC)
 	})
 }
 
@@ -149,7 +150,7 @@ func (proc *Processor) decodeMutation(
 	content, valueMAC = content[:len(content)-32], content[len(content)-32:]
 	if validateMACs {
 		expectedValueMAC := generateContentMAC(mutation.GetOperation(), content, keyID, keys.ValueMAC)
-		if !bytes.Equal(expectedValueMAC, valueMAC) {
+		if !hmac.Equal(expectedValueMAC, valueMAC) {
 			err = fmt.Errorf("failed to verify mutation #%d: %w", i+1, ErrMismatchingContentMAC)
 			return
 		}
@@ -169,7 +170,7 @@ func (proc *Processor) decodeMutation(
 	indexMAC = mutation.GetRecord().GetIndex().GetBlob()
 	if validateMACs {
 		expectedIndexMAC := concatAndHMAC(sha256.New, keys.Index, syncAction.Index)
-		if !bytes.Equal(expectedIndexMAC, indexMAC) {
+		if !hmac.Equal(expectedIndexMAC, indexMAC) {
 			err = fmt.Errorf("failed to verify mutation #%d: %w", i+1, ErrMismatchingIndexMAC)
 			return
 		}
@@ -248,7 +249,7 @@ func (proc *Processor) validateSnapshotMAC(ctx context.Context, name WAPatchName
 		return
 	}
 	snapshotMAC := currentState.generateSnapshotMAC(name, keys.SnapshotMAC)
-	if !bytes.Equal(snapshotMAC, expectedSnapshotMAC) {
+	if !hmac.Equal(snapshotMAC, expectedSnapshotMAC) {
 		err = fmt.Errorf("failed to verify patch v%d: %w", currentState.Version, ErrMismatchingLTHash)
 	}
 	return
@@ -321,7 +322,7 @@ func (proc *Processor) validatePatch(
 	newState.Version = version
 	warn, err = newState.updateHash(patch.GetMutations(), func(indexMAC []byte, maxIndex int) ([]byte, error) {
 		for i := maxIndex - 1; i >= 0; i-- {
-			if bytes.Equal(patch.Mutations[i].GetRecord().GetIndex().GetBlob(), indexMAC) {
+			if hmac.Equal(patch.Mutations[i].GetRecord().GetIndex().GetBlob(), indexMAC) {
 				if patch.Mutations[i].GetOperation() == waServerSync.SyncdMutation_SET {
 					value := patch.Mutations[i].GetRecord().GetValue().GetBlob()
 					return value[len(value)-32:], nil
@@ -345,7 +346,7 @@ func (proc *Processor) validatePatch(
 			return
 		}
 		patchMAC := generatePatchMAC(patch, patchName, keys.PatchMAC, patch.GetVersion().GetVersion())
-		if !bytes.Equal(patchMAC, patch.GetPatchMAC()) {
+		if !hmac.Equal(patchMAC, patch.GetPatchMAC()) {
 			err = fmt.Errorf("failed to verify patch v%d: %w", version, ErrMismatchingPatchMAC)
 			return
 		}

appstate/keys.go

@@ -38,33 +38,34 @@ var AllPatchNames = [...]WAPatchName{WAPatchCriticalBlock, WAPatchCriticalUnbloc
 
 // Constants for the regular_low app state indexes.
 const (
-	IndexPin                       = "pin_v1"
-	IndexRecentEmojiWeightsAction  = "recent_emoji_weights_action"
-	IndexArchive                   = "archive"
-	IndexSentinel                  = "sentinel"
-	IndexMarkChatAsRead            = "markChatAsRead"
-	IndexSettingUnarchiveChats     = "setting_unarchiveChats"
-	IndexAndroidUnsupportedActions = "android_unsupported_actions"
-	IndexTimeFormat                = "time_format"
-	IndexNux                       = "nux"
-	IndexPrimaryVersion            = "primary_version"
-	IndexFavoriteSticker           = "favoriteSticker"
-	IndexRemoveRecentSticker       = "removeRecentSticker"
-	IndexBotWelcomeRequest         = "bot_welcome_request"
-	IndexPaymentInfo               = "payment_info"
-	IndexCustomPaymentMethods      = "custom_payment_methods"
-	IndexLock                      = "lock"
-	IndexSettingChatLock           = "setting_chatLock"
-	IndexDeviceCapabilities        = "device_capabilities"
-	IndexNoteEdit                  = "note_edit"
-	IndexMerchantPaymentPartner    = "merchant_payment_partner"
-	IndexPaymentTOS                = "payment_tos"
-	IndexAIThreadRename            = "ai_thread_rename"
-	IndexInteractiveMessageAction  = "interactive_message_action"
-	IndexSettingsSync              = "settings_sync"
-	IndexOutContact                = "out_contact"
-	IndexCustomerData              = "customer_data"
-	IndexThreadPin                 = "thread_pin"
+	IndexPin                             = "pin_v1"
+	IndexRecentEmojiWeightsAction        = "recent_emoji_weights_action"
+	IndexArchive                         = "archive"
+	IndexSentinel                        = "sentinel"
+	IndexMarkChatAsRead                  = "markChatAsRead"
+	IndexSettingUnarchiveChats           = "setting_unarchiveChats"
+	IndexAndroidUnsupportedActions       = "android_unsupported_actions"
+	IndexTimeFormat                      = "time_format"
+	IndexNux                             = "nux"
+	IndexPrimaryVersion                  = "primary_version"
+	IndexFavoriteSticker                 = "favoriteSticker"
+	IndexRemoveRecentSticker             = "removeRecentSticker"
+	IndexBotWelcomeRequest               = "bot_welcome_request"
+	IndexPaymentInfo                     = "payment_info"
+	IndexCustomPaymentMethods            = "custom_payment_methods"
+	IndexLock                            = "lock"
+	IndexSettingChatLock                 = "setting_chatLock"
+	IndexDeviceCapabilities              = "device_capabilities"
+	IndexNoteEdit                        = "note_edit"
+	IndexMerchantPaymentPartner          = "merchant_payment_partner"
+	IndexPaymentTOS                      = "payment_tos"
+	IndexAIThreadRename                  = "ai_thread_rename"
+	IndexInteractiveMessageAction        = "interactive_message_action"
+	IndexSettingsSync                    = "settings_sync"
+	IndexOutContact                      = "out_contact"
+	IndexCustomerData                    = "customer_data"
+	IndexThreadPin                       = "thread_pin"
+	IndexSettingAutoOrganizeBusinessChat = "setting_autoOrganizeBusinessChat"
 )
 
 // Constants for the regular app state indexes.
@@ -120,6 +121,7 @@ const (
 	IndexPrivateProcessingSetting                     = "private_processing_setting"
 	IndexAIThreadDelete                               = "ai_thread_delete"
 	IndexNCTSaltSync                                  = "nct_salt_sync"
+	IndexBizAISettingsNudgeAction                     = "biz_ai_settings_nudge_action"
 )
 
 // Constants for the critical_unblock_low app state indexes.

client.go

@@ -26,6 +26,7 @@ import (
 	"go.mau.fi/util/ptr"
 	"go.mau.fi/util/random"
 	"golang.org/x/net/proxy"
+	"golang.org/x/sync/semaphore"
 
 	"go.mau.fi/whatsmeow/appstate"
 	waBinary "go.mau.fi/whatsmeow/binary"
@@ -99,9 +100,10 @@ type Client struct {
 	appStateProc     *appstate.Processor
 	appStateSyncLock sync.Mutex
 
-	historySyncNotifications  chan *waE2E.HistorySyncNotification
-	historySyncHandlerStarted atomic.Bool
-	ManualHistorySyncDownload bool
+	historySyncNotifications        chan *waE2E.HistorySyncNotification
+	historySyncHandlerStarted       atomic.Bool
+	ManualHistorySyncDownload       bool
+	DisableManualHistorySyncReceipt bool
 
 	uploadPreKeysLock sync.Mutex
 	lastPreKeyUpload  time.Time
@@ -119,6 +121,7 @@ type Client struct {
 
 	messageRetries     map[string]int
 	messageRetriesLock sync.Mutex
+	retrySema          *semaphore.Weighted
 
 	incomingRetryRequestCounter     map[incomingRetryKey]int
 	incomingRetryRequestCounterLock sync.Mutex
@@ -128,6 +131,12 @@ type Client struct {
 
 	messageSendLock sync.Mutex
 
+	tcTokenSenderTS            map[types.JID]time.Time
+	tcTokenSenderTSLock        sync.Mutex
+	lastTCTokenSenderTSCleanup time.Time
+	tcTokenDBPruneLock         sync.Mutex
+	lastTCTokenDBPrune         time.Time
+
 	privacySettingsCache atomic.Value
 
 	groupCache           map[types.JID]*groupMetaCache
@@ -159,7 +168,12 @@ type Client struct {
 	// from the usync query (meaning they're not on WhatsApp). The callback receives the JIDs
 	// that had no devices. This allows the application to passively learn which contacts are
 	// inactive without making separate IsOnWhatsApp calls.
-	OnNoDeviceContacts func(jids []types.JID)
+	//
+	// The callback runs in a new goroutine. Panics are recovered and logged with a stack trace
+	// so application code panics don't crash the worker. Use SetMaxParallelNoDeviceContactsCallbacks
+	// to bound concurrent invocations under heavy GetUserDevices load.
+	OnNoDeviceContacts   func(jids []types.JID)
+	noDeviceContactsSema *semaphore.Weighted
 
 	// PrePairCallback is called before pairing is completed. If it returns false, the pairing will be cancelled and
 	// the client will disconnect.
@@ -168,6 +182,7 @@ type Client struct {
 	// GetClientPayload is called to get the client payload for connecting to the server.
 	// This should NOT be used for WhatsApp (to change the OS name, update fields in store.BaseClientPayload directly).
 	GetClientPayload func() *waWa6.ClientPayload
+	QRClientType     PairClientType
 
 	// Should untrusted identity errors be handled automatically? If true, the stored identity and existing signal
 	// sessions will be removed on untrusted identity errors, and an events.IdentityChange will be dispatched.
@@ -262,6 +277,7 @@ func NewClient(deviceStore *store.Device, log waLog.Logger) *Client {
 
 		historySyncNotifications: make(chan *waE2E.HistorySyncNotification, 32),
 
+		tcTokenSenderTS:  make(map[types.JID]time.Time),
 		groupCache:       make(map[types.JID]*groupMetaCache),
 		userDevicesCache: make(map[types.JID]deviceCache),
 
@@ -409,6 +425,27 @@ func (cli *Client) SetPreLoginHTTPClient(h *http.Client) {
 	cli.preLoginHTTP = h
 }
 
+// SetMaxParallelRetryReceiptHandling sets how many retry receipts can be handled in parallel.
+// Defaults to unlimited. This should only be set before connecting, changing it afterwards can cause data races.
+func (cli *Client) SetMaxParallelRetryReceiptHandling(n int64) {
+	if n <= 0 {
+		cli.retrySema = nil
+	} else {
+		cli.retrySema = semaphore.NewWeighted(n)
+	}
+}
+
+// SetMaxParallelNoDeviceContactsCallbacks sets how many OnNoDeviceContacts callback goroutines
+// can run in parallel. Defaults to unlimited. This should only be set before connecting,
+// changing it afterwards can cause data races.
+func (cli *Client) SetMaxParallelNoDeviceContactsCallbacks(n int64) {
+	if n <= 0 {
+		cli.noDeviceContactsSema = nil
+	} else {
+		cli.noDeviceContactsSema = semaphore.NewWeighted(n)
+	}
+}
+
 func (cli *Client) getSocketWaitChan() <-chan struct{} {
 	cli.socketLock.RLock()
 	ch := cli.socketWait

connectionevents.go

@@ -177,10 +177,9 @@ func (cli *Client) handleConnectSuccess(ctx context.Context, node *waBinary.Node
 		} else {
 			cli.Log.Infof("Updated LID to %s", cli.Store.LID)
 		}
+		cli.StoreLIDPNMapping(ctx, cli.Store.GetLID(), cli.Store.GetJID())
 	}
-	// Some users are missing their own LID-PN mapping even though it's already in the device table,
-	// so do this unconditionally for a few months to ensure everyone gets the row.
-	cli.StoreLIDPNMapping(ctx, cli.Store.GetLID(), cli.Store.GetJID())
+	cli.deleteExpiredPrivacyTokens()
 	go func() {
 		if dbCount, err := cli.Store.PreKeys.UploadedPreKeyCount(ctx); err != nil {
 			cli.Log.Errorf("Failed to get number of prekeys in database: %v", err)

cstoken.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Tulir Asokan
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+package whatsmeow
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+
+	"go.mau.fi/whatsmeow/types"
+)
+
+func shouldSendCsToken(jid types.JID) bool {
+	jid = jid.ToNonAD()
+	return (jid.Server == types.DefaultUserServer || jid.Server == types.HiddenUserServer) &&
+		jid.User != types.PSAJID.User &&
+		!jid.IsBot()
+}
+
+// derives a cstoken for the given JID using HMAC-SHA256(nctSalt, recipientLID).
+func (cli *Client) generateCsToken(ctx context.Context, jid types.JID) []byte {
+	if !shouldSendCsToken(jid) {
+		return nil
+	}
+	if cli.Store == nil || cli.Store.NCTSalt == nil {
+		return nil
+	}
+	salt, err := cli.Store.NCTSalt.GetNCTSalt(ctx)
+	if err != nil {
+		cli.Log.Debugf("Failed to load NCT salt for cstoken: %v", err)
+		return nil
+	}
+	if len(salt) == 0 {
+		return nil
+	}
+	var recipientLID types.JID
+	switch jid.Server {
+	case types.HiddenUserServer:
+		recipientLID = jid.ToNonAD()
+	case types.DefaultUserServer:
+		if cli.Store == nil || cli.Store.LIDs == nil {
+			return nil
+		}
+		pn := jid.ToNonAD()
+		lid, err := cli.Store.LIDs.GetLIDForPN(ctx, pn)
+		if err != nil {
+			cli.Log.Debugf("Failed to resolve LID for cstoken JID %s: %v", pn, err)
+			return nil
+		}
+		if lid.IsEmpty() {
+			return nil
+		}
+		recipientLID = lid.ToNonAD()
+	default:
+		return nil
+	}
+
+	if recipientLID.Server != types.HiddenUserServer {
+		return nil
+	}
+
+	h := hmac.New(sha256.New, salt)
+	h.Write([]byte(recipientLID.String()))
+	return h.Sum(nil)
+}
+
+func (cli *Client) storeNCTSalt(ctx context.Context, salt []byte) error {
+	if cli.Store == nil || cli.Store.NCTSalt == nil {
+		return nil
+	}
+	if len(salt) == 0 {
+		return nil
+	}
+	return cli.Store.NCTSalt.PutNCTSalt(ctx, salt)
+}
+
+func (cli *Client) clearNCTSalt(ctx context.Context) error {
+	if cli.Store == nil || cli.Store.NCTSalt == nil {
+		return nil
+	}
+	return cli.Store.NCTSalt.DeleteNCTSalt(ctx)
+}