appstate

Documentation

Overview

Package appstate implements encoding and decoding WhatsApp's app state patches.

Index

• Constants
• Variables
• func ParseRecovery(...) (*waSyncdSnapshotRecovery.SyncdSnapshotRecovery, error)
• type DownloadExternalFunc
• type ExpandedAppStateKeys
• type HashState
• type Mutation
• type MutationInfo
• type PatchInfo
  • func BuildArchive(target types.JID, archive bool, lastMessageTimestamp time.Time, ...) PatchInfo
  • func BuildDeleteChat(target types.JID, lastMessageTimestamp time.Time, ...) PatchInfo
  • func BuildLabelChat(target types.JID, labelID string, labeled bool) PatchInfo
  • func BuildLabelEdit(labelID string, labelName string, labelColor int32, deleted bool) PatchInfo
  • func BuildLabelMessage(target types.JID, labelID, messageID string, labeled bool) PatchInfo
  • func BuildMarkChatAsRead(target types.JID, read bool, lastMessageTimestamp time.Time, ...) PatchInfo
  • func BuildMute(target types.JID, mute bool, muteDuration time.Duration) PatchInfo
  • func BuildMuteAbs(target types.JID, mute bool, muteEndTimestamp *int64) PatchInfo
  • func BuildPin(target types.JID, pin bool) PatchInfo
  • func BuildSettingPushName(pushName string) PatchInfo
  • func BuildStar(target, sender types.JID, messageID types.MessageID, fromMe, starred bool) PatchInfo
• type PatchList
  • func ParsePatchList(ctx context.Context, collection *waBinary.Node, ...) (*PatchList, error)
• type Processor
  • func NewProcessor(store *store.Device, log waLog.Logger) *Processor
  • func (proc *Processor) DecodePatches(ctx context.Context, list *PatchList, initialState HashState, ...) (newMutations []Mutation, currentState HashState, err error)
  • func (proc *Processor) EncodePatch(ctx context.Context, keyID []byte, state HashState, patchInfo PatchInfo) ([]byte, error)
  • func (proc *Processor) GetMissingKeyIDs(ctx context.Context, pl *PatchList) [][]byte
  • func (proc *Processor) ProcessRecovery(ctx context.Context, recovery *waSyncdSnapshotRecovery.SyncdSnapshotRecovery) ([]Mutation, error)
• type WAPatchName

Constants

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"
	IndexSettingAutoOrganizeBusinessChat = "setting_autoOrganizeBusinessChat"
	IndexCoexV2Version                   = "coexV2Version"
)

Constants for the regular_low app state indexes.

const (
	IndexQuickReply                                      = "quick_reply"
	IndexLabelAssociationMessage                         = "label_message"
	IndexLabelEdit                                       = "label_edit"
	IndexLabelAssociationChat                            = "label_jid"
	IndexPrimaryFeature                                  = "primary_feature"
	IndexDeviceAgent                                     = "deviceAgent"
	IndexSubscription                                    = "subscription"
	IndexAgentChatAssignment                             = "agentChatAssignment"
	IndexAgentChatAssignmentOpenedStatus                 = "agentChatAssignmentOpenedStatus"
	IndexPNForLIDChat                                    = "pnForLidChat"
	IndexMarketingMessage                                = "marketingMessage"
	IndexMarketingMessageBroadcast                       = "marketingMessageBroadcast"
	IndexExternalWebBeta                                 = "external_web_beta"
	IndexSettingRelayAllCalls                            = "setting_relayAllCalls"
	IndexCallLog                                         = "call_log"
	IndexDeleteIndividualCallLog                         = "delete_individual_call_log"
	IndexLabelReordering                                 = "label_reordering"
	IndexSettingDisableLinkPreviews                      = "setting_disableLinkPreviews"
	IndexUsernameChatStartMode                           = "usernameChatStartMode"
	IndexNotificationActivitySetting                     = "notificationActivitySetting"
	IndexSettingChannelsPersonalisedRecommendationOptout = "setting_channels_personalised_recommendation_optout"
	IndexBroadcastJID                                    = "broadcast_jid"
	IndexDetectedOutcomesStatusAction                    = "detected_outcomes_status_action"
	IndexBusinessBroadcastList                           = "business_broadcast_list"
	IndexMusicUserID                                     = "music_user_id"
	IndexAvatarUpdatedAction                             = "avatar_updated_action"
	IndexGalaxyFlowAction                                = "galaxy_flow_action"
	IndexNewsletterSavedInterests                        = "newsletter_saved_interests"
	IndexShareOwnPN                                      = "shareOwnPn"
	IndexBroadcast                                       = "broadcast"
	IndexSubscriptionsSync                               = "subscriptions_sync_v2"
)

Constants for the regular app state indexes.

const (
	IndexStar                                         = "star"
	IndexMute                                         = "mute"
	IndexDeleteMessageForMe                           = "deleteMessageForMe"
	IndexClearChat                                    = "clearChat"
	IndexDeleteChat                                   = "deleteChat"
	IndexUserStatusMute                               = "userStatusMute"
	IndexUGCBot                                       = "ugc_bot"
	IndexStatusPrivacy                                = "status_privacy"
	IndexFavorites                                    = "favorites"
	IndexWaffleAccountLinkState                       = "waffle_account_link_state"
	IndexCTWAPerCustomerDataSharing                   = "ctwaPerCustomerDataSharing"
	IndexMaibaAIFeaturesControl                       = "maiba_ai_features_control"
	IndexStatusPostOptInNotificationPreferencesAction = "status_post_opt_in_notification_preferences_action"
	IndexPrivateProcessingSetting                     = "private_processing_setting"
	IndexAIThreadDelete                               = "ai_thread_delete"
	IndexNCTSaltSync                                  = "nct_salt_sync"
	IndexBizAISettingsNudgeAction                     = "biz_ai_settings_nudge"
	IndexWasaRootSecretAction                         = "wasa_root_secret"
)

Constants for the regular_high app state indexes.

const (
	IndexContact    = "contact"
	IndexLIDContact = "lid_contact"
)

Constants for the critical_unblock_low app state indexes.

const (
	IndexSettingSecurityNotification = "setting_securityNotification"
	IndexSettingPushName             = "setting_pushName"
	IndexSettingLocale               = "setting_locale"
	IndexGeneratedWUI                = "generated_wui"
)

Constants for the critical_block app state indexes.

Variables

var (
	ErrMissingPreviousSetValueOperation = errors.New("missing value MAC of previous SET operation")
	ErrMismatchingLTHash                = errors.New("mismatching LTHash")
	ErrMismatchingPatchMAC              = errors.New("mismatching patch MAC")
	ErrMismatchingContentMAC            = errors.New("mismatching content MAC")
	ErrMismatchingIndexMAC              = errors.New("mismatching index MAC")
	ErrKeyNotFound                      = errors.New("didn't find app state key")
)

Errors that this package can return.

var AllPatchNames = [...]WAPatchName{WAPatchCriticalBlock, WAPatchCriticalUnblockLow, WAPatchRegularHigh, WAPatchRegular, WAPatchRegularLow}

AllPatchNames contains all currently known patch state names.

Functions

func ParseRecovery

func ParseRecovery(
	resp *waE2E.PeerDataOperationRequestResponseMessage_PeerDataOperationResult_SyncDSnapshotFatalRecoveryResponse,
) (*waSyncdSnapshotRecovery.SyncdSnapshotRecovery, error)

Types

type DownloadExternalFunc

type DownloadExternalFunc func(context.Context, *waServerSync.ExternalBlobReference) ([]byte, error)

DownloadExternalFunc is a function that can download a blob of external app state patches.

type ExpandedAppStateKeys

type ExpandedAppStateKeys struct {
	Index           []byte
	ValueEncryption []byte
	ValueMAC        []byte
	SnapshotMAC     []byte
	PatchMAC        []byte
}

type HashState

type HashState struct {
	Version uint64
	Hash    [128]byte
}

type Mutation

type Mutation struct {
	KeyID     []byte
	Operation waServerSync.SyncdMutation_SyncdOperation
	Action    *waSyncAction.SyncActionValue
	Version   int32
	Index     []string
	IndexMAC  []byte
	ValueMAC  []byte

	PatchVersion uint64
}

type MutationInfo

type MutationInfo struct {
	// Index contains the thing being mutated (like `mute` or `pin_v1`), followed by parameters like the target JID.
	Index []string
	// Version is a static number that depends on the thing being mutated.
	Version int32
	// Value contains the data for the mutation.
	Value *waSyncAction.SyncActionValue
}

MutationInfo contains information about a single mutation to the app state.

type PatchInfo

type PatchInfo struct {
	// Timestamp is the time when the patch was created. This will be filled automatically in EncodePatch if it's zero.
	Timestamp time.Time
	// Type is the app state type being mutated.
	Type WAPatchName
	// Mutations contains the individual mutations to apply to the app state in this patch.
	Mutations []MutationInfo
}

PatchInfo contains information about a patch to the app state. A patch can contain multiple mutations, as long as all mutations are in the same app state type.

func BuildArchive

func BuildArchive(target types.JID, archive bool, lastMessageTimestamp time.Time, lastMessageKey *waCommon.MessageKey) PatchInfo

BuildArchive builds an app state patch for archiving or unarchiving a chat.

The last message timestamp and last message key are optional and can be set to zero values (`time.Time{}` and `nil`).

Archiving a chat will also unpin it automatically.

func BuildDeleteChat

func BuildDeleteChat(target types.JID, lastMessageTimestamp time.Time, lastMessageKey *waCommon.MessageKey, deleteMedia bool) PatchInfo

BuildDeleteChat builds an app state patch for deleting a chat.

func BuildLabelChat

func BuildLabelChat(target types.JID, labelID string, labeled bool) PatchInfo

BuildLabelChat builds an app state patch for labeling or un(labeling) a chat.

func BuildLabelEdit

func BuildLabelEdit(labelID string, labelName string, labelColor int32, deleted bool) PatchInfo

BuildLabelEdit builds an app state patch for editing a label.

func BuildLabelMessage

func BuildLabelMessage(target types.JID, labelID, messageID string, labeled bool) PatchInfo

BuildLabelMessage builds an app state patch for labeling or un(labeling) a message.

func BuildMarkChatAsRead

func BuildMarkChatAsRead(target types.JID, read bool, lastMessageTimestamp time.Time, lastMessageKey *waCommon.MessageKey) PatchInfo

BuildMarkChatAsRead builds an app state patch for marking a chat as read or unread.

func BuildMute

func BuildMute(target types.JID, mute bool, muteDuration time.Duration) PatchInfo

BuildMute builds an app state patch for muting or unmuting a chat.

If mute is true and the mute duration is zero, the chat is muted forever.

func BuildMuteAbs

func BuildMuteAbs(target types.JID, mute bool, muteEndTimestamp *int64) PatchInfo

BuildMuteAbs builds an app state patch for muting or unmuting a chat with an absolute timestamp.

func BuildPin

func BuildPin(target types.JID, pin bool) PatchInfo

BuildPin builds an app state patch for pinning or unpinning a chat.

func BuildSettingPushName

func BuildSettingPushName(pushName string) PatchInfo

BuildSettingPushName builds an app state patch for setting the push name.

func BuildStar

func BuildStar(target, sender types.JID, messageID types.MessageID, fromMe, starred bool) PatchInfo

BuildStar builds an app state patch for starring or unstarring a message.

type PatchList

type PatchList struct {
	Name           WAPatchName
	HasMorePatches bool
	Patches        []*waServerSync.SyncdPatch
	Snapshot       *waServerSync.SyncdSnapshot
}

PatchList represents a decoded response to getting app state patches from the WhatsApp servers.

func ParsePatchList

func ParsePatchList(ctx context.Context, collection *waBinary.Node, downloadExternal DownloadExternalFunc) (*PatchList, error)

ParsePatchList will decode an XML node containing app state patches, including downloading any external blobs.

type Processor

type Processor struct {
	Store *store.Device
	Log   waLog.Logger
	// contains filtered or unexported fields
}

func NewProcessor

func NewProcessor(store *store.Device, log waLog.Logger) *Processor

func (*Processor) DecodePatches

func (proc *Processor) DecodePatches(
	ctx context.Context,
	list *PatchList,
	initialState HashState,
	validateMACs bool,
) (newMutations []Mutation, currentState HashState, err error)

DecodePatches will decode all the patches in a PatchList into a list of app state mutations.

func (*Processor) EncodePatch

func (proc *Processor) EncodePatch(ctx context.Context, keyID []byte, state HashState, patchInfo PatchInfo) ([]byte, error)

func (*Processor) GetMissingKeyIDs

func (proc *Processor) GetMissingKeyIDs(ctx context.Context, pl *PatchList) [][]byte

func (*Processor) ProcessRecovery

func (proc *Processor) ProcessRecovery(ctx context.Context, recovery *waSyncdSnapshotRecovery.SyncdSnapshotRecovery) ([]Mutation, error)

type WAPatchName

type WAPatchName string

WAPatchName represents a type of app state patch.

const (
	// WAPatchCriticalBlock contains the user's settings like push name and locale.
	WAPatchCriticalBlock WAPatchName = "critical_block"
	// WAPatchCriticalUnblockLow contains the user's contact list.
	WAPatchCriticalUnblockLow WAPatchName = "critical_unblock_low"
	// WAPatchRegularLow contains some local chat settings like pin, archive status, and the setting of whether to unarchive chats when messages come in.
	WAPatchRegularLow WAPatchName = "regular_low"
	// WAPatchRegularHigh contains more local chat settings like mute status and starred messages.
	WAPatchRegularHigh WAPatchName = "regular_high"
	// WAPatchRegular contains protocol info about app state patches like key expiration.
	WAPatchRegular WAPatchName = "regular"
)