@zervonex/baileys 0.0.0-stage → 3.0.1

package/lib/Socket/messages-recv.js

@@ -0,0 +1,904 @@
+import NodeCache from '@cacheable/node-cache'
+import { Boom } from '@hapi/boom'
+import { randomBytes } from 'crypto'
+import { proto } from '../../WAProto/index.js'
+import { DEFAULT_CACHE_TTLS, KEY_BUNDLE_TYPE, MIN_PREKEY_COUNT, PLACEHOLDER_MAX_AGE_SECONDS, STATUS_EXPIRY_SECONDS } from '../Defaults/index.js'
+import { WAMessageStatus, WAMessageStubType } from '../Types/index.js'
+import {
+  aesDecryptCTR, aesEncryptGCM, cleanMessage, Curve, decodeMediaRetryNode,
+  decodeMessageNode, makeMutex, decryptMessageNode, delay, derivePairingCodeKey,
+  encodeBigEndian, encodeSignedDeviceIdentity, extractAddressingContext,
+  extractE2ESessionFromRetryReceipt, getCallStatusFromNode, getHistoryMsg,
+  getNextPreKeys, getStatusFromReceiptType, extractMessageText,
+  handleIdentityChange, hkdf, MISSING_KEYS_ERROR_TEXT, NACK_REASONS,
+  NO_MESSAGE_FOUND_ERROR_TEXT, SERVER_ERROR_CODES, toNumber, unixTimestampSeconds,
+  xmppPreKey, xmppSignedPreKey, ACCOUNT_RESTRICTED_TEXT, buildMergedTcTokenIndexWrite,
+  isTcTokenExpired, readTcTokenIndex, resolveTcTokenJid, resolveIssuanceJid,
+  storeTcTokensFromIqResult, TC_TOKEN_INDEX_KEY, decryptMsmsgBotMessage,
+  decodeDecryptedMsmsgMessage, extractReportingInfoFromStanza, getContentType,
+} from '../Utils/index.js'
+import {
+  areJidsSameUser, binaryNodeToString, getAllBinaryNodeChildren, getBinaryNodeChild,
+  getBinaryNodeChildBuffer, getBinaryNodeChildren, getBinaryNodeChildString,
+  getBinaryNodeChildUInt, isJidGroup, isJidNewsletter, isJidStatusBroadcast,
+  isLidUser, isPnUser, jidDecode, jidNormalizedUser, S_WHATSAPP_NET, jidEncode,
+} from '../WABinary/index.js'
+import { extractGroupMetadata } from './groups.js'
+import { makeMessagesSocket } from './messages-send.js'
+
+// ─── Pure stanza builders ─────────────────────────────────────────────────────
+
+export const buildGroupCallStanza = ({ id, to, callId, callCreator, offerContent }) => ({
+  tag: 'call',
+  attrs: { id, to },
+  content: [{ tag: 'offer', attrs: { 'call-id': callId, 'call-creator': callCreator, type: 'group', 'group-jid': to }, content: offerContent }]
+})
+
+export const buildGroupCallCancelStanza = ({ to, callId, callCreator }) => ({
+  tag: 'call',
+  attrs: { from: callCreator, to },
+  content: [{ tag: 'terminate', attrs: { 'call-id': callId, 'call-creator': callCreator, reason: 'user-terminated', count: '0' }, content: undefined }]
+})
+
+// ─── Socket ───────────────────────────────────────────────────────────────────
+
+export const makeMessagesRecvSocket = (config) => {
+  const { logger, retryRequestDelayMs, maxMsgRetryCount, getMessage, shouldIgnoreJid, enableAutoSessionRecreation } = config
+  const sock = makeMessagesSocket(config)
+  const { ev, authState, ws, processingMutex, signalRepository, query, upsertMessage, resyncAppState, onUnexpectedError, assertSessions, sendNode, relayMessage, sendReceipt, uploadPreKeys, sendPeerDataOperationMessage, messageRetryManager, registerSocketEndHandler, issuePrivacyTokens, fetchAccountReachoutTimelock, placeholderResendCache: sockPlaceholderResendCache } = sock
+
+  const getLIDForPN = signalRepository.lidMapping.getLIDForPN.bind(signalRepository.lidMapping)
+  const { messageMutex, notificationMutex, receiptMutex: _receiptMutex, placeholderResendCache } = sock
+  const retryMutex = makeMutex()
+  const msgRetryCache = config.msgRetryCounterCache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.MSG_RETRY, useClones: false })
+  const callOfferCache = config.callOfferCache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.CALL_OFFER, useClones: false })
+  const identityAssertDebounce = new NodeCache({ stdTTL: 5, useClones: false })
+  const inFlightPreKeyLow = new Set()
+  const inFlight463Recoveries = new Set()
+
+  let sendActiveReceipts = false
+
+  // ── PDO helpers ───────────────────────────────────────────────────────────
+
+  const fetchMessageHistory = async (count, oldestMsgKey, oldestMsgTimestamp) => {
+    if (!authState.creds.me?.id) throw new Boom('Not authenticated')
+    return sendPeerDataOperationMessage({ historySyncOnDemandRequest: { chatJid: oldestMsgKey.remoteJid, oldestMsgFromMe: oldestMsgKey.fromMe, oldestMsgId: oldestMsgKey.id, oldestMsgTimestampMs: oldestMsgTimestamp, onDemandMsgCount: count }, peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.HISTORY_SYNC_ON_DEMAND })
+  }
+
+  const requestPlaceholderResend = async (messageKey, msgData) => {
+    if (!authState.creds.me?.id) throw new Boom('Not authenticated')
+    if (await placeholderResendCache.get(messageKey?.id)) { logger.debug({ messageKey }, 'already requested resend'); return }
+    await placeholderResendCache.set(messageKey?.id, msgData || true)
+    await delay(2000)
+    if (!(await placeholderResendCache.get(messageKey?.id))) { logger.debug({ messageKey }, 'message received while resend requested'); return 'RESOLVED' }
+    setTimeout(async () => { if (await placeholderResendCache.get(messageKey?.id)) { logger.debug({ messageKey }, 'PDO message without response after 8 seconds. Phone possibly offline'); await placeholderResendCache.del(messageKey?.id) } }, 8000)
+    return sendPeerDataOperationMessage({ placeholderMessageResendRequest: [{ messageKey }], peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.PLACEHOLDER_MESSAGE_RESEND })
+  }
+
+  const requestContactRefresh = async (jids) => {
+    if (!jids?.length) return
+    return sendPeerDataOperationMessage({ contactRefreshRequest: { jids: Array.isArray(jids) ? jids : [jids] }, peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.CONTACT_REFRESH_REQUEST })
+  }
+
+  // ── Newsletter notifications ──────────────────────────────────────────────
+
+  const handleMexNewsletterNotification = async (node) => {
+    const mexNode = getBinaryNodeChild(node, 'mex')
+    if (!mexNode?.content) return
+    let data
+    try { data = JSON.parse(mexNode.content.toString()) } catch { return }
+    const { operation, updates } = data || {}
+    if (!updates || !operation) return
+    logger.info({ operation, updates }, 'got mex newsletter notification')
+    switch (operation) {
+      case 'NotificationNewsletterUpdate':
+        for (const update of updates) if (update.jid && update.settings && Object.keys(update.settings).length > 0) ev.emit('newsletter-settings.update', { id: update.jid, update: update.settings })
+        break
+      case 'NotificationNewsletterAdminPromote':
+        for (const update of updates) if (update.jid && update.user) ev.emit('newsletter-participants.update', { id: update.jid, author: node.attrs.from, user: update.user, new_role: 'ADMIN', action: 'promote' })
+        break
+      default:
+        logger.info({ operation, data }, 'Unhandled mex newsletter notification')
+    }
+  }
+
+  const handleNewsletterNotification = async (node) => {
+    const from = node.attrs.from
+    const child = getAllBinaryNodeChildren(node)[0]
+    const author = node.attrs.participant
+    logger.info({ from, child }, 'got newsletter notification')
+    switch (child.tag) {
+      case 'reaction':
+        ev.emit('newsletter.reaction', { id: from, server_id: child.attrs.message_id, reaction: { code: getBinaryNodeChildString(child, 'reaction'), count: 1 } })
+        break
+      case 'view':
+        ev.emit('newsletter.view', { id: from, server_id: child.attrs.message_id, count: parseInt(child.content?.toString() || '0', 10) })
+        break
+      case 'participant':
+        ev.emit('newsletter-participants.update', { id: from, author, user: child.attrs.jid, action: child.attrs.action, new_role: child.attrs.role })
+        break
+      case 'update':
+        const settingsNode = getBinaryNodeChild(child, 'settings')
+        if (settingsNode) {
+          const update = {}
+          const nameNode = getBinaryNodeChild(settingsNode, 'name')
+          if (nameNode?.content) update.name = nameNode.content.toString()
+          const descNode = getBinaryNodeChild(settingsNode, 'description')
+          if (descNode?.content) update.description = descNode.content.toString()
+          ev.emit('newsletter-settings.update', { id: from, update })
+        }
+        break
+      case 'message':
+        const plaintextNode = getBinaryNodeChild(child, 'plaintext')
+        if (plaintextNode?.content) {
+          try {
+            const buf = typeof plaintextNode.content === 'string' ? Buffer.from(plaintextNode.content, 'binary') : Buffer.from(plaintextNode.content)
+            const messageProto = proto.Message.decode(buf).toJSON()
+            const fullMessage = proto.WebMessageInfo.fromObject({ key: { remoteJid: from, id: child.attrs.message_id || child.attrs.server_id, fromMe: false }, message: messageProto, messageTimestamp: +child.attrs.t }).toJSON()
+            await upsertMessage(fullMessage, 'append')
+          } catch (error) { logger.error({ error }, 'Failed to decode plaintext newsletter message') }
+        }
+        break
+      default:
+        logger.warn({ node }, 'Unknown newsletter notification')
+    }
+  }
+
+  // ── ACK / call helpers ────────────────────────────────────────────────────
+
+  const sendMessageAck = async (node, errorCode) => {
+    const { tag, attrs, content } = node
+    const hasUnavailable = !!getBinaryNodeChild({ tag, attrs, content }, 'unavailable')
+    const stanza = { tag: 'ack', attrs: { id: attrs.id, to: attrs.from, class: tag } }
+    if (errorCode) stanza.attrs.error = errorCode.toString()
+    if (attrs.participant) stanza.attrs.participant = attrs.participant
+    if (attrs.recipient) stanza.attrs.recipient = attrs.recipient
+    if (attrs.type || hasUnavailable || errorCode) stanza.attrs.type = attrs.type
+    if (tag === 'message' && authState.creds.me?.id) stanza.attrs.from = authState.creds.me.id
+    logger.debug({ recv: { tag, attrs }, sent: stanza.attrs }, 'sent ack')
+    try { await sendNode(stanza) } catch (error) {
+      if (error?.output?.statusCode === 428 || error?.message?.includes('Connection')) logger.warn({ id: attrs.id, error: error?.message }, 'Failed to send ACK (connection closed) - message already received')
+      else throw error
+    }
+  }
+
+  const rejectCall = async (callId, callFrom) => {
+    await query({ tag: 'call', attrs: { from: authState.creds.me.id, to: callFrom }, content: [{ tag: 'reject', attrs: { 'call-id': callId, 'call-creator': callFrom, count: '0' }, content: undefined }] })
+  }
+
+  const offerCall = async (toJid, isVideo = false) => {
+    const callId = randomBytes(16).toString('hex').toUpperCase().substring(0, 64)
+    const offerContent = []
+    offerContent.push({ tag: 'audio', attrs: { enc: 'opus', rate: '16000' }, content: undefined })
+    offerContent.push({ tag: 'audio', attrs: { enc: 'opus', rate: '8000' }, content: undefined })
+    if (isVideo) offerContent.push({ tag: 'video', attrs: { orientation: '0', screen_width: '1920', screen_height: '1080', device_orientation: '0', enc: 'vp8', dec: 'vp8' } })
+    offerContent.push({ tag: 'net', attrs: { medium: '3' }, content: undefined })
+    offerContent.push({ tag: 'capability', attrs: { ver: '1' }, content: new Uint8Array([1, 4, 255, 131, 207, 4]) })
+    offerContent.push({ tag: 'encopt', attrs: { keygen: '2' }, content: undefined })
+    const encKey = randomBytes(32)
+    const devices = (await getUSyncDevices([toJid], true, false)).map(({ user, device }) => jidEncode(user, 's.whatsapp.net', device))
+    await assertSessions(devices, true)
+    const { nodes: destinations, shouldIncludeDeviceIdentity } = await createParticipantNodes(devices, { call: { callKey: encKey } }, {})
+    offerContent.push({ tag: 'destination', attrs: {}, content: destinations })
+    if (shouldIncludeDeviceIdentity) offerContent.push({ tag: 'device-identity', attrs: {}, content: encodeSignedDeviceIdentity(authState.creds.account, true) })
+    await query({ tag: 'call', attrs: { to: toJid }, content: [{ tag: 'offer', attrs: { 'call-id': callId, 'call-creator': authState.creds.me.id }, content: offerContent }] })
+    return { callId, toJid, isVideo }
+  }
+
+  // ── Retry logic ───────────────────────────────────────────────────────────
+
+  const sendRetryRequest = async (node, forceIncludeKeys = false) => {
+    const { fullMessage } = decodeMessageNode(node, authState.creds.me.id, authState.creds.me.lid || '')
+    const { key: msgKey } = fullMessage
+    const msgId = msgKey.id
+
+    if (messageRetryManager) {
+      if (messageRetryManager.hasExceededMaxRetries(msgId)) { logger.debug({ msgId }, 'reached retry limit with new retry manager, clearing'); messageRetryManager.markRetryFailed(msgId); return }
+      const retryCount = messageRetryManager.incrementRetryCount(msgId)
+      await msgRetryCache.set(`${msgId}:${msgKey?.participant}`, retryCount)
+    } else {
+      const key = `${msgId}:${msgKey?.participant}`
+      let retryCount = (await msgRetryCache.get(key)) || 0
+      if (retryCount >= maxMsgRetryCount) { logger.debug({ retryCount, msgId }, 'reached retry limit, clearing'); await msgRetryCache.del(key); return }
+      await msgRetryCache.set(key, retryCount + 1)
+    }
+
+    const retryCount = (await msgRetryCache.get(`${msgId}:${msgKey?.participant}`)) || 1
+    const { account, signedPreKey, signedIdentityKey: identityKey } = authState.creds
+    const fromJid = node.attrs.from
+    let shouldRecreateSession = false, recreateReason = ''
+
+    if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1) {
+      try {
+        const sessionId = signalRepository.jidToSignalProtocolAddress(fromJid)
+        const hasSession = await signalRepository.validateSession(fromJid)
+        let lidJid = null
+        if (isPnUser(fromJid)) lidJid = await signalRepository.lidMapping.getLIDForPN(fromJid)
+        const result = messageRetryManager.shouldRecreateSession(fromJid, retryCount, hasSession.exists)
+        shouldRecreateSession = result.recreate; recreateReason = result.reason
+        if (shouldRecreateSession) {
+          logger.debug({ fromJid, lidJid, retryCount, reason: recreateReason }, 'recreating session for retry')
+          await authState.keys.set({ session: { [sessionId]: null } })
+          if (lidJid) await authState.keys.set({ session: { [signalRepository.jidToSignalProtocolAddress(lidJid)]: null } })
+          forceIncludeKeys = true
+        }
+      } catch (error) { logger.warn({ error, fromJid }, 'failed to check session recreation') }
+    }
+
+    if (retryCount <= 2) {
+      if (messageRetryManager) {
+        messageRetryManager.schedulePhoneRequest(msgId, async () => {
+          try { const requestId = await requestPlaceholderResend(msgKey); logger.debug(`sendRetryRequest: requested placeholder resend (${requestId}) for message ${msgId} (scheduled)`) }
+          catch (error) { logger.warn({ error, msgId }, 'failed to send scheduled phone request') }
+        })
+      } else {
+        const id = await requestPlaceholderResend(msgKey)
+        logger.debug(`sendRetryRequest: requested placeholder resend for message ${id}`)
+      }
+    }
+
+    const deviceIdentity = encodeSignedDeviceIdentity(account, true)
+    await authState.keys.transaction(async () => {
+      const receipt = { tag: 'receipt', attrs: { id: msgId, type: 'retry', to: node.attrs.from }, content: [{ tag: 'retry', attrs: { count: retryCount.toString(), id: node.attrs.id, t: node.attrs.t, v: '1', error: '0' } }, { tag: 'registration', attrs: {}, content: encodeBigEndian(authState.creds.registrationId) }] }
+      if (node.attrs.recipient) receipt.attrs.recipient = node.attrs.recipient
+      if (node.attrs.participant) receipt.attrs.participant = node.attrs.participant
+      if (retryCount > 1 || forceIncludeKeys || shouldRecreateSession) {
+        const { update, preKeys } = await getNextPreKeys(authState, 1)
+        const [keyId] = Object.keys(preKeys)
+        const key = preKeys[+keyId]
+        receipt.content.push({ tag: 'keys', attrs: {}, content: [{ tag: 'type', attrs: {}, content: Buffer.from(KEY_BUNDLE_TYPE) }, { tag: 'identity', attrs: {}, content: identityKey.public }, xmppPreKey(key, +keyId), xmppSignedPreKey(signedPreKey), { tag: 'device-identity', attrs: {}, content: deviceIdentity }] })
+        ev.emit('creds.update', update)
+      }
+      await sendNode(receipt)
+      logger.info({ msgAttrs: node.attrs, retryCount }, 'sent retry receipt')
+    }, authState?.creds?.me?.id || 'sendRetryRequest')
+  }
+
+  // ── TC token helpers ──────────────────────────────────────────────────────
+
+  const reissueTcTokenAfterIdentityChange = (from) => {
+    void (async () => {
+      const normalizedJid = jidNormalizedUser(from)
+      const tcJid = await resolveTcTokenJid(normalizedJid, getLIDForPN)
+      const tcTokenData = await authState.keys.get('tctoken', [tcJid])
+      const senderTs = tcTokenData?.[tcJid]?.senderTimestamp
+      if (senderTs === null || senderTs === undefined || isTcTokenExpired(senderTs)) return
+      logger.debug({ jid: normalizedJid, senderTimestamp: senderTs }, 'identity changed, re-issuing tctoken')
+      const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
+      const issueToLid = sock.serverProps?.lidTrustedTokenIssueToLid ?? false
+      const issueJid = await resolveIssuanceJid(normalizedJid, issueToLid, getLIDForPN, getPNForLID)
+      const result = await issuePrivacyTokens([issueJid], senderTs)
+      await storeTcTokensFromIqResult({ result, fallbackJid: tcJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
+    })().catch(err => logger.debug({ jid: from, err: err?.message }, 'failed to re-issue tctoken after identity change'))
+  }
+
+  const handlePrivacyTokenNotification = async (node) => {
+    const tokensNode = getBinaryNodeChild(node, 'tokens')
+    if (!tokensNode) return
+    const from = jidNormalizedUser(node.attrs.from)
+    const senderLid = node.attrs.sender_lid && isLidUser(jidNormalizedUser(node.attrs.sender_lid)) ? jidNormalizedUser(node.attrs.sender_lid) : undefined
+    const fallbackJid = senderLid ?? (await resolveTcTokenJid(from, getLIDForPN))
+    logger.debug({ from, storageJid: fallbackJid }, 'processing privacy token notification')
+    await storeTcTokensFromIqResult({ result: node, fallbackJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
+  }
+
+  const tcTokenKnownJids = new Set()
+  const tcTokenIndexLoaded = (async () => {
+    try { const jids = await readTcTokenIndex(authState.keys); for (const jid of jids) tcTokenKnownJids.add(jid); if (tcTokenKnownJids.size > 0) logger.debug({ count: tcTokenKnownJids.size }, 'loaded tctoken index') }
+    catch (err) { logger.warn({ err: err?.message }, 'failed to load tctoken index') }
+  })()
+
+  let tcTokenIndexTimer
+  const flushTcTokenIndex = async () => {
+    if (tcTokenIndexTimer) { clearTimeout(tcTokenIndexTimer); tcTokenIndexTimer = undefined }
+    const write = await buildMergedTcTokenIndexWrite(authState.keys, tcTokenKnownJids)
+    return authState.keys.set({ tctoken: write })
+  }
+  const scheduleTcTokenIndexSave = () => {
+    if (tcTokenIndexTimer) clearTimeout(tcTokenIndexTimer)
+    tcTokenIndexTimer = setTimeout(() => { tcTokenIndexTimer = undefined; flushTcTokenIndex().catch(err => logger.warn({ err: err?.message }, 'failed to save tctoken index')) }, 5000)
+  }
+  const trackTcTokenJid = (jid) => { if (jid && jid !== TC_TOKEN_INDEX_KEY && !tcTokenKnownJids.has(jid)) { tcTokenKnownJids.add(jid); scheduleTcTokenIndexSave() } }
+
+  // ── Encrypt notification ──────────────────────────────────────────────────
+
+  const handleEncryptNotification = async (node) => {
+    const from = node.attrs.from
+    if (from === S_WHATSAPP_NET) {
+      const stanzaId = node.attrs.id
+      if (stanzaId && inFlightPreKeyLow.has(stanzaId)) return
+      const count = +getBinaryNodeChild(node, 'count').attrs.value
+      logger.debug({ count, shouldUploadMorePreKeys: count < MIN_PREKEY_COUNT }, 'recv pre-key count')
+      if (count < MIN_PREKEY_COUNT) {
+        if (stanzaId) inFlightPreKeyLow.add(stanzaId)
+        try { await uploadPreKeys() } finally { if (stanzaId) inFlightPreKeyLow.delete(stanzaId) }
+      }
+    } else {
+      const result = await handleIdentityChange(node, { meId: authState.creds.me?.id, meLid: authState.creds.me?.lid, validateSession: signalRepository.validateSession, assertSessions, debounceCache: identityAssertDebounce, logger, onBeforeSessionRefresh: reissueTcTokenAfterIdentityChange })
+      if (result.action === 'no_identity_node') logger.info({ node }, 'unknown encrypt notification')
+    }
+  }
+
+  // ── Group notification ────────────────────────────────────────────────────
+
+  const handleGroupNotification = (fullNode, child, msg) => {
+    const actingParticipantLid = fullNode.attrs.participant
+    const actingParticipantPn = fullNode.attrs.participant_pn
+    const affectedParticipantLid = getBinaryNodeChild(child, 'participant')?.attrs?.jid || actingParticipantLid
+    const affectedParticipantPn = getBinaryNodeChild(child, 'participant')?.attrs?.phone_number || actingParticipantPn
+    switch (child?.tag) {
+      case 'create':
+        const metadata = extractGroupMetadata(child)
+        msg.messageStubType = WAMessageStubType.GROUP_CREATE
+        msg.messageStubParameters = [metadata.subject]
+        msg.key = { participant: metadata.owner, participantAlt: metadata.ownerPn }
+        ev.emit('chats.upsert', [{ id: metadata.id, name: metadata.subject, conversationTimestamp: metadata.creation }])
+        ev.emit('groups.upsert', [{ ...metadata, author: actingParticipantLid, authorPn: actingParticipantPn }])
+        break
+      case 'ephemeral':
+      case 'not_ephemeral':
+        msg.message = { protocolMessage: { type: proto.Message.ProtocolMessage.Type.EPHEMERAL_SETTING, ephemeralExpiration: +(child.attrs.expiration || 0) } }
+        break
+      case 'modify':
+        const modifiedParticipants = getBinaryNodeChildren(child, 'participant').map(({ attrs }) => ({ id: attrs.jid, phoneNumber: isPnUser(attrs.phone_number) ? attrs.phone_number : undefined, lid: isLidUser(attrs.lid) ? attrs.lid : undefined, admin: attrs.type || null }))
+        msg.messageStubParameters = modifiedParticipants.map(a => JSON.stringify(a))
+        msg.messageStubType = WAMessageStubType.GROUP_PARTICIPANT_CHANGE_NUMBER
+        break
+      case 'promote':
+      case 'demote':
+      case 'remove':
+      case 'add':
+      case 'leave':
+        msg.messageStubType = WAMessageStubType[`GROUP_PARTICIPANT_${child.tag.toUpperCase()}`]
+        const participants = getBinaryNodeChildren(child, 'participant').map(({ attrs }) => ({ id: attrs.jid, phoneNumber: isLidUser(attrs.jid) && isPnUser(attrs.phone_number) ? attrs.phone_number : undefined, lid: isPnUser(attrs.jid) && isLidUser(attrs.lid) ? attrs.lid : undefined, admin: attrs.type || null }))
+        if (participants.length === 1 && (areJidsSameUser(participants[0].id, actingParticipantLid) || areJidsSameUser(participants[0].id, actingParticipantPn)) && child.tag === 'remove') msg.messageStubType = WAMessageStubType.GROUP_PARTICIPANT_LEAVE
+        msg.messageStubParameters = participants.map(a => JSON.stringify(a))
+        break
+      case 'subject':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_SUBJECT
+        msg.messageStubParameters = [child.attrs.subject]
+        break
+      case 'description':
+        const description = getBinaryNodeChild(child, 'body')?.content?.toString()
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_DESCRIPTION
+        msg.messageStubParameters = description ? [description] : undefined
+        break
+      case 'announcement':
+      case 'not_announcement':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_ANNOUNCE
+        msg.messageStubParameters = [child.tag === 'announcement' ? 'on' : 'off']
+        break
+      case 'locked':
+      case 'unlocked':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_RESTRICT
+        msg.messageStubParameters = [child.tag === 'locked' ? 'on' : 'off']
+        break
+      case 'invite':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_INVITE_LINK
+        msg.messageStubParameters = [child.attrs.code]
+        break
+      case 'member_add_mode':
+        const addMode = child.content
+        if (addMode) { msg.messageStubType = WAMessageStubType.GROUP_MEMBER_ADD_MODE; msg.messageStubParameters = [addMode.toString()] }
+        break
+      case 'membership_approval_mode':
+        const approvalMode = getBinaryNodeChild(child, 'group_join')
+        if (approvalMode) { msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_MODE; msg.messageStubParameters = [approvalMode.attrs.state] }
+        break
+      case 'created_membership_requests':
+        msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_REQUEST_NON_ADMIN_ADD
+        msg.messageStubParameters = [JSON.stringify({ lid: affectedParticipantLid, pn: affectedParticipantPn }), 'created', child.attrs.request_method]
+        break
+      case 'revoked_membership_requests':
+        const isDenied = areJidsSameUser(affectedParticipantLid, actingParticipantLid)
+        msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_REQUEST_NON_ADMIN_ADD
+        msg.messageStubParameters = [JSON.stringify({ lid: affectedParticipantLid, pn: affectedParticipantPn }), isDenied ? 'revoked' : 'rejected']
+        break
+    }
+  }
+
+  // ── Devices notification ──────────────────────────────────────────────────
+
+  const handleDevicesNotification = async (node) => {
+    const [child] = getAllBinaryNodeChildren(node)
+    const from = jidNormalizedUser(node.attrs.from)
+    if (!child) { logger.debug({ from }, 'devices notification missing child, skipping'); return }
+    const tag = child.tag
+    const deviceHash = child.attrs.device_hash
+    const devices = getBinaryNodeChildren(child, 'device')
+    if (areJidsSameUser(from, authState.creds.me.id) || areJidsSameUser(from, authState.creds.me.lid)) logger.info({ deviceJids: devices.map(d => d.attrs.jid) }, 'got my own devices')
+    if (!devices.length) { logger.debug({ from, tag }, 'no devices in notification, skipping'); return }
+    const decoded = []
+    for (const d of devices) { const jid = d.attrs.jid; if (!jid) continue; const parts = jidDecode(jid); if (!parts) { logger.debug({ jid }, 'failed to decode device jid, skipping'); continue }; decoded.push({ jid, user: parts.user, server: parts.server, device: parts.device }) }
+    if (!decoded.length) return
+    await sock.devicesMutex.mutex(async () => {
+      const byUser = new Map()
+      for (const d of decoded) { const list = byUser.get(d.user) || []; list.push(d); byUser.set(d.user, list) }
+      for (const [user, entries] of byUser) {
+        if (tag === 'update') { logger.debug({ user }, `${user}'s device list updated, dropping cached devices`); await sock.userDevicesCache?.del(user); continue }
+        if (tag === 'remove') await signalRepository.deleteSession(entries.map(e => e.jid))
+        const existingCache = (await sock.userDevicesCache?.get(user)) || []
+        if (!existingCache.length) { logger.debug({ user, tag }, 'device list not cached, deferring to USync refresh'); continue }
+        const affected = new Set(entries.map(e => e.device))
+        let updatedDevices
+        switch (tag) {
+          case 'add': logger.info({ deviceHash, count: entries.length }, 'devices added'); updatedDevices = [...existingCache.filter(d => !affected.has(d.device)), ...entries.map(e => ({ user: e.user, server: e.server, device: e.device }))]; break
+          case 'remove': logger.info({ deviceHash, count: entries.length }, 'devices removed'); updatedDevices = existingCache.filter(d => !affected.has(d.device)); break
+          default: logger.debug({ tag }, 'unknown device list change tag'); continue
+        }
+        if (updatedDevices.length === 0) await sock.userDevicesCache?.del(user)
+        else await sock.userDevicesCache?.set(user, updatedDevices)
+      }
+    })
+  }
+
+  // ── processNotification ───────────────────────────────────────────────────
+
+  const processNotification = async (node) => {
+    const result = {}
+    const [child] = getAllBinaryNodeChildren(node)
+    const nodeType = node.attrs.type
+    const from = jidNormalizedUser(node.attrs.from)
+    switch (nodeType) {
+      case 'privacy_token': await handlePrivacyTokenNotification(node); break
+      case 'newsletter': await handleNewsletterNotification(node); break
+      case 'mex': await handleMexNewsletterNotification(node); break
+      case 'w:gp2': handleGroupNotification(node, child, result); break
+      case 'mediaretry': ev.emit('messages.media-update', [decodeMediaRetryNode(node)]); break
+      case 'encrypt': await handleEncryptNotification(node); break
+      case 'devices':
+        try { await handleDevicesNotification(node) } catch (error) { logger.error({ error, node }, 'failed to handle devices notification') }
+        break
+      case 'server_sync':
+        const update = getBinaryNodeChild(node, 'collection')
+        if (update) await resyncAppState([update.attrs.name], false)
+        break
+      case 'picture':
+        const setPicture = getBinaryNodeChild(node, 'set')
+        const delPicture = getBinaryNodeChild(node, 'delete')
+        ev.emit('contacts.update', [{ id: jidNormalizedUser(node?.attrs?.from) || (setPicture || delPicture)?.attrs?.hash || '', imgUrl: setPicture ? 'changed' : 'removed' }])
+        if (isJidGroup(from)) {
+          const pictureNode = setPicture || delPicture
+          result.messageStubType = WAMessageStubType.GROUP_CHANGE_ICON
+          if (setPicture) result.messageStubParameters = [setPicture.attrs.id]
+          result.participant = pictureNode?.attrs.author
+          result.key = { ...(result.key || {}), participant: setPicture?.attrs.author }
+        }
+        break
+      case 'account_sync':
+        if (child.tag === 'disappearing_mode') {
+          const newDuration = +child.attrs.duration
+          logger.info({ newDuration }, 'updated account disappearing mode')
+          ev.emit('creds.update', { accountSettings: { ...authState.creds.accountSettings, defaultDisappearingMode: { ephemeralExpiration: newDuration, ephemeralSettingTimestamp: +child.attrs.t } } })
+        } else if (child.tag === 'blocklist') {
+          for (const { attrs } of getBinaryNodeChildren(child, 'item')) ev.emit('blocklist.update', { blocklist: [attrs.jid], type: attrs.action === 'block' ? 'add' : 'remove' })
+        }
+        break
+      case 'link_code_companion_reg':
+        const linkCodeNode = getBinaryNodeChild(node, 'link_code_companion_reg')
+        const ref = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'link_code_pairing_ref'))
+        const primaryIdentityPublicKey = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'primary_identity_pub'))
+        const primaryEphemeralWrapped = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'link_code_pairing_wrapped_primary_ephemeral_pub'))
+        const codePairingPublicKey = await decipherLinkPublicKey(primaryEphemeralWrapped)
+        const companionSharedKey = Curve.sharedKey(authState.creds.pairingEphemeralKeyPair.private, codePairingPublicKey)
+        const random = randomBytes(32)
+        const linkCodeSalt = randomBytes(32)
+        const linkCodePairingExpanded = hkdf(companionSharedKey, 32, { salt: linkCodeSalt, info: 'link_code_pairing_key_bundle_encryption_key' })
+        const encryptPayload = Buffer.concat([Buffer.from(authState.creds.signedIdentityKey.public), primaryIdentityPublicKey, random])
+        const encryptIv = randomBytes(12)
+        const encrypted = aesEncryptGCM(encryptPayload, linkCodePairingExpanded, encryptIv, Buffer.alloc(0))
+        const encryptedPayload = Buffer.concat([linkCodeSalt, encryptIv, encrypted])
+        const identitySharedKey = Curve.sharedKey(authState.creds.signedIdentityKey.private, primaryIdentityPublicKey)
+        const identityPayload = Buffer.concat([companionSharedKey, identitySharedKey, random])
+        authState.creds.advSecretKey = Buffer.from(hkdf(identityPayload, 32, { info: 'adv_secret' })).toString('base64')
+        await query({ tag: 'iq', attrs: { to: S_WHATSAPP_NET, type: 'set', id: sock.generateMessageTag(), xmlns: 'md' }, content: [{ tag: 'link_code_companion_reg', attrs: { jid: authState.creds.me.id, stage: 'companion_finish' }, content: [{ tag: 'link_code_pairing_wrapped_key_bundle', attrs: {}, content: encryptedPayload }, { tag: 'companion_identity_public', attrs: {}, content: authState.creds.signedIdentityKey.public }, { tag: 'link_code_pairing_ref', attrs: {}, content: ref }] }] })
+        authState.creds.registered = true
+        ev.emit('creds.update', authState.creds)
+        break
+    }
+    if (Object.keys(result).length) return result
+  }
+
+  // ── Link pairing helpers ──────────────────────────────────────────────────
+
+  const decipherLinkPublicKey = async (data) => {
+    const buffer = toRequiredBuffer(data)
+    const salt = buffer.slice(0, 32)
+    const secretKey = await derivePairingCodeKey(authState.creds.pairingCode, salt)
+    const iv = buffer.slice(32, 48)
+    const payload = buffer.slice(48, 80)
+    return aesDecryptCTR(payload, secretKey, iv)
+  }
+
+  const toRequiredBuffer = (data) => {
+    if (data === undefined) throw new Boom('Invalid buffer', { statusCode: 400 })
+    return data instanceof Buffer ? data : Buffer.from(data)
+  }
+
+  // ── Retry helpers ─────────────────────────────────────────────────────────
+
+  const willSendMessageAgain = async (id, participant) => { const retryCount = (await msgRetryCache.get(`${id}:${participant}`)) || 0; return retryCount < maxMsgRetryCount }
+  const updateSendMessageAgainCount = async (id, participant) => { const key = `${id}:${participant}`; await msgRetryCache.set(key, ((await msgRetryCache.get(key)) || 0) + 1) }
+
+  const sendMessagesAgain = async (key, ids, retryNode, receiptNode) => {
+    const remoteJid = key.remoteJid
+    const participant = key.participant || remoteJid
+    const retryCount = +retryNode.attrs.count || 1
+    const msgs = []
+
+    for (const id of ids) {
+      let msg
+      if (messageRetryManager) { const cached = messageRetryManager.getRecentMessage(remoteJid, id); if (cached) { msg = cached.message; logger.debug({ jid: remoteJid, id }, 'found message in retry cache'); messageRetryManager.markRetrySuccess(id) } }
+      if (!msg) { msg = await getMessage({ ...key, id }); if (msg) { logger.debug({ jid: remoteJid, id }, 'found message via getMessage'); if (messageRetryManager) messageRetryManager.markRetrySuccess(id) } }
+      msgs.push(msg)
+    }
+
+    const sendToAll = !jidDecode(participant)?.device
+    const sessionId = signalRepository.jidToSignalProtocolAddress(participant)
+    let injectedFromBundle = false
+    const bundle = extractE2ESessionFromRetryReceipt(receiptNode)
+
+    if (bundle) {
+      try { await signalRepository.injectE2ESession({ jid: participant, session: bundle }); injectedFromBundle = true; logger.debug({ participant, retryCount }, 'injected session from retry receipt key bundle') }
+      catch (error) { logger.warn({ error, participant }, 'failed to inject session from retry receipt') }
+    }
+
+    if (!injectedFromBundle && typeof signalRepository.getSessionInfo === 'function') {
+      const receivedRegId = getBinaryNodeChildUInt(receiptNode, 'registration', 4)
+      if (typeof receivedRegId === 'number' && Number.isInteger(receivedRegId)) {
+        const info = await signalRepository.getSessionInfo(participant)
+        if (info && info.registrationId !== 0 && info.registrationId !== receivedRegId) { logger.info({ participant, stored: info.registrationId, received: receivedRegId }, 'reg id mismatch on retry without bundle, deleting session'); await authState.keys.set({ session: { [sessionId]: null } }) }
+      }
+    }
+
+    if (ids[0] && messageRetryManager && typeof messageRetryManager.saveBaseKey === 'function') {
+      const info = typeof signalRepository.getSessionInfo === 'function' ? await signalRepository.getSessionInfo(participant) : undefined
+      if (info) {
+        if (retryCount === 2) messageRetryManager.saveBaseKey(sessionId, ids[0], info.baseKey)
+        else if (retryCount > 2) {
+          if (messageRetryManager.hasSameBaseKey(sessionId, ids[0], info.baseKey)) { logger.warn({ participant, retryCount }, 'base key collision on retry, forcing fresh session'); await authState.keys.set({ session: { [sessionId]: null } }) }
+          messageRetryManager.deleteBaseKey(sessionId, ids[0])
+        }
+      }
+    }
+
+    let shouldRecreateSession = false, recreateReason = ''
+    if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1 && !injectedFromBundle) {
+      try {
+        const hasSession = await signalRepository.validateSession(participant)
+        const result = messageRetryManager.shouldRecreateSession(participant, retryCount, hasSession.exists)
+        shouldRecreateSession = result.recreate; recreateReason = result.reason
+        if (shouldRecreateSession) { logger.debug({ participant, retryCount, reason: recreateReason }, 'recreating session for outgoing retry'); await authState.keys.set({ session: { [sessionId]: null } }) }
+      } catch (error) { logger.warn({ error, participant }, 'failed to check session recreation for outgoing retry') }
+    }
+
+    if (!injectedFromBundle) await assertSessions([participant], true)
+    if (isJidGroup(remoteJid)) await authState.keys.set({ 'sender-key-memory': { [remoteJid]: null } })
+    logger.debug({ participant, sendToAll, shouldRecreateSession, recreateReason, injectedFromBundle }, 'preparing retry recp')
+
+    for (const [i, msg] of msgs.entries()) {
+      if (!ids[i]) continue
+      if (msg && (await willSendMessageAgain(ids[i], participant))) {
+        await updateSendMessageAgainCount(ids[i], participant)
+        const msgRelayOpts = { messageId: ids[i] }
+        if (sendToAll) msgRelayOpts.useUserDevicesCache = false
+        else msgRelayOpts.participant = { jid: participant, count: +retryNode.attrs.count }
+        await relayMessage(key.remoteJid, msg, msgRelayOpts)
+      } else logger.debug({ jid: key.remoteJid, id: ids[i] }, 'recv retry request, but message not available')
+    }
+  }
+
+  // ── handleReceipt ─────────────────────────────────────────────────────────
+
+  const handleReceipt = async (node) => {
+    const { attrs, content } = node
+    const isLid = attrs.from.includes('lid')
+    const isNodeFromMe = areJidsSameUser(attrs.participant || attrs.from, isLid ? authState.creds.me?.lid : authState.creds.me?.id)
+    const remoteJid = !isNodeFromMe || isJidGroup(attrs.from) ? attrs.from : attrs.recipient
+    const fromMe = !attrs.recipient || ((attrs.type === 'retry' || attrs.type === 'sender') && isNodeFromMe)
+    const key = { remoteJid, id: '', fromMe, participant: attrs.participant }
+    if (shouldIgnoreJid(remoteJid) && remoteJid !== S_WHATSAPP_NET) { logger.debug({ remoteJid }, 'ignoring receipt from jid'); await sendMessageAck(node); return }
+    const ids = [attrs.id]
+    if (Array.isArray(content)) ids.push(...getBinaryNodeChildren(content[0], 'item').map(i => i.attrs.id))
+    try {
+      await Promise.all([processingMutex.mutex(async () => {
+        const status = getStatusFromReceiptType(attrs.type)
+        if (typeof status !== 'undefined' && (status >= proto.WebMessageInfo.Status.SERVER_ACK || !isNodeFromMe)) {
+          if (isJidGroup(remoteJid) || isJidStatusBroadcast(remoteJid)) {
+            if (attrs.participant) {
+              const updateKey = status === proto.WebMessageInfo.Status.DELIVERY_ACK ? 'receiptTimestamp' : 'readTimestamp'
+              ev.emit('message-receipt.update', ids.map(id => ({ key: { ...key, id }, receipt: { userJid: jidNormalizedUser(attrs.participant), [updateKey]: +attrs.t } })))
+            }
+          } else ev.emit('messages.update', ids.map(id => ({ key: { ...key, id }, update: { status, messageTimestamp: toNumber(+(attrs.t ?? 0)) } })))
+        }
+        if (attrs.type === 'retry') {
+          key.participant = key.participant || attrs.from
+          const retryNode = getBinaryNodeChild(node, 'retry')
+          if (ids[0] && key.participant && (await willSendMessageAgain(ids[0], key.participant))) {
+            if (key.fromMe) {
+              try { await updateSendMessageAgainCount(ids[0], key.participant); logger.debug({ attrs, key }, 'recv retry request'); await sendMessagesAgain(key, ids, retryNode, node) }
+              catch (error) { logger.error({ key, ids, trace: error instanceof Error ? error.stack : 'Unknown error' }, 'error in sending message again') }
+            } else logger.info({ attrs, key }, 'recv retry for not fromMe message')
+          } else {
+            logger.info({ attrs, key, participant: key.participant }, 'retry limit exhausted - clearing broken session')
+            try {
+              await signalRepository.deleteSession([key.participant])
+              await msgRetryCache.del(`${ids[0]}:${key.participant}`)
+            } catch (err) { logger.error({ err, participant: key.participant }, 'failed to clear session/cache at retry exhaustion') }
+          }
+        }
+      })])
+    } finally { await sendMessageAck(node) }
+  }
+
+  // ── handleNotification ────────────────────────────────────────────────────
+
+  const handleNotification = async (node) => {
+    const remoteJid = node.attrs.from
+    if (shouldIgnoreJid(remoteJid) && remoteJid !== S_WHATSAPP_NET) { logger.debug({ remoteJid, id: node.attrs.id }, 'ignored notification'); await sendMessageAck(node); return }
+    try {
+      await Promise.all([notificationMutex.mutex(async () => {
+        const msg = await processNotification(node)
+        if (msg) {
+          const fromMe = areJidsSameUser(node.attrs.participant || remoteJid, authState.creds.me.id)
+          const { senderAlt: participantAlt, addressingMode } = extractAddressingContext(node)
+          msg.key = { remoteJid, fromMe, participant: node.attrs.participant, participantAlt, addressingMode, id: node.attrs.id, ...(msg.key || {}) }
+          msg.participant ?? (msg.participant = node.attrs.participant)
+          msg.messageTimestamp = +node.attrs.t
+          await upsertMessage(proto.WebMessageInfo.fromObject(msg), 'append')
+        }
+      })])
+    } finally { await sendMessageAck(node) }
+  }
+
+  // ── handleMessage ─────────────────────────────────────────────────────────
+
+  const handleMessage = async (node) => {
+    if (shouldIgnoreJid(node.attrs.from) && node.attrs.from !== S_WHATSAPP_NET) { logger.debug({ key: node.attrs.key }, 'ignored message'); await sendMessageAck(node, NACK_REASONS.UnhandledError); return }
+
+    const encNode = getBinaryNodeChild(node, 'enc')
+    if (encNode && encNode.attrs.type === 'msmsg') {
+      const encIv = getBinaryNodeChildBuffer(encNode, 'enc_iv')
+      const encPayload = getBinaryNodeChildBuffer(encNode, 'enc_p') || encNode.content
+      if (!encIv || !encPayload) { logger.debug({ id: node.attrs.id, from: node.attrs.from, hasIv: !!encIv, hasPayload: !!encPayload }, 'msmsg missing enc_iv or enc_p, cannot decrypt'); await sendMessageAck(node); return }
+      try {
+        const messageSecret = authState.creds.myAppStateKeyId ? Buffer.from(authState.creds.myAppStateKeyId, 'base64') : undefined
+        if (!messageSecret) { logger.debug({ key: node.attrs.key }, 'no message secret for msmsg, skipping'); await sendMessageAck(node, NACK_REASONS.MissingMessageSecret); return }
+        const messageKey = { participant: node.attrs.participant || node.attrs.from, meId: authState.creds.me.id, meLid: authState.creds.me.lid, conversationJid: node.attrs.from, senderJid: node.attrs.participant, stanzaId: node.attrs.id, targetId: node.attrs.id }
+        const decrypted = await decryptMsmsgBotMessage(messageSecret, messageKey, { encPayload, encIv })
+        node.attrs._msmsgDecrypted = decodeDecryptedMsmsgMessage(decrypted)
+        logger.debug({ key: node.attrs.key }, 'decrypted msmsg bot message')
+      } catch (err) { logger.warn({ err, id: node.attrs.id }, 'failed to decrypt msmsg, falling back to nack'); await sendMessageAck(node, NACK_REASONS.MissingMessageSecret); return }
+    }
+
+    const { fullMessage: msg, category, author, decrypt } = decryptMessageNode(node, authState.creds.me.id, authState.creds.me.lid || '', signalRepository, logger)
+    const alt = msg.key.participantAlt || msg.key.remoteJidAlt
+    if (!!alt) {
+      const altServer = jidDecode(alt)?.server
+      const primaryJid = msg.key.participant || msg.key.remoteJid
+      if (altServer === 'lid') { if (!(await signalRepository.lidMapping.getPNForLID(alt))) { await signalRepository.lidMapping.storeLIDPNMappings([{ lid: alt, pn: primaryJid }]); await signalRepository.migrateSession(primaryJid, alt) } }
+      else { await signalRepository.lidMapping.storeLIDPNMappings([{ lid: primaryJid, pn: alt }]); await signalRepository.migrateSession(alt, primaryJid) }
+    }
+
+    let acked = false
+    try {
+      await messageMutex.mutex(async () => {
+        await decrypt()
+        if (msg.key?.remoteJid && msg.key?.id && msg.message && messageRetryManager) messageRetryManager.addRecentMessage(msg.key.remoteJid, msg.key.id, msg.message)
+
+        if (msg.messageStubType === proto.WebMessageInfo.StubType.CIPHERTEXT && msg.category !== 'peer') {
+          if (msg?.messageStubParameters?.[0] === MISSING_KEYS_ERROR_TEXT) { acked = true; return sendMessageAck(node, NACK_REASONS.ParsingError) }
+          if (msg.messageStubParameters?.[0] === NO_MESSAGE_FOUND_ERROR_TEXT) {
+            const unavailableNode = getBinaryNodeChild(node, 'unavailable')
+            const unavailableType = unavailableNode?.attrs?.type
+            if (['bot_unavailable_fanout', 'hosted_unavailable_fanout', 'view_once_unavailable_fanout'].includes(unavailableType)) { logger.debug({ msgId: msg.key.id, unavailableType }, 'skipping placeholder resend for excluded unavailable type'); acked = true; return sendMessageAck(node) }
+            const messageAge = unixTimestampSeconds() - toNumber(msg.messageTimestamp)
+            if (messageAge > PLACEHOLDER_MAX_AGE_SECONDS) { logger.debug({ msgId: msg.key.id, messageAge }, 'skipping placeholder resend for old message'); acked = true; return sendMessageAck(node) }
+            const cleanKey = { remoteJid: msg.key.remoteJid, fromMe: msg.key.fromMe, id: msg.key.id, participant: msg.key.participant }
+            const msgData = { key: msg.key, messageTimestamp: msg.messageTimestamp, pushName: msg.pushName, participant: msg.participant, verifiedBizName: msg.verifiedBizName }
+            requestPlaceholderResend(cleanKey, msgData).then(requestId => { if (requestId && requestId !== 'RESOLVED') { logger.debug({ msgId: msg.key.id, requestId }, 'requested placeholder resend for unavailable message'); ev.emit('messages.update', [{ key: msg.key, update: { messageStubParameters: [NO_MESSAGE_FOUND_ERROR_TEXT, requestId] } }]) } }).catch(err => logger.warn({ err, msgId: msg.key.id }, 'failed to request placeholder resend for unavailable message'))
+            acked = true; await sendMessageAck(node)
+          } else {
+            if ((msg.messageStubParameters?.[0] || '').includes('InvalidPreKeyId')) { logger.debug({ msgId: msg.key.id, remoteJid: msg.key.remoteJid }, 'skipping retry for InvalidPreKeyId, sender must re-establish session'); acked = true; return sendMessageAck(node, NACK_REASONS.UnhandledError) }
+            if (isJidStatusBroadcast(msg.key.remoteJid)) {
+              const messageAge = unixTimestampSeconds() - toNumber(msg.messageTimestamp)
+              if (messageAge > STATUS_EXPIRY_SECONDS) { logger.debug({ msgId: msg.key.id, messageAge, remoteJid: msg.key.remoteJid }, 'skipping retry for expired status message'); acked = true; return sendMessageAck(node) }
+            }
+            retryMutex.mutex(async () => {
+              try { if (!ws.isOpen) { logger.debug({ node }, 'Connection closed, skipping retry'); return }; await sendRetryRequest(node, true); if (retryRequestDelayMs) await delay(retryRequestDelayMs) }
+              catch (err) { logger.error({ err }, 'Retry mechanism failed'); try { await sendRetryRequest(node, !getBinaryNodeChild(node, 'enc')) } catch (retryErr) { logger.error({ retryErr }, 'Final retry attempt failed') } }
+              acked = true; await sendMessageAck(node, NACK_REASONS.UnhandledError)
+            })
+          }
+        } else {
+          if (messageRetryManager && msg.key.id) messageRetryManager.cancelPendingPhoneRequest(msg.key.id)
+          const isNewsletter = isJidNewsletter(msg.key.remoteJid)
+          if (!isNewsletter) {
+            let type = undefined, participant = msg.key.participant
+            if (category === 'peer') type = 'peer_msg'
+            else if (msg.key.fromMe) { type = 'sender'; if (isLidUser(msg.key.remoteJid) || isLidUser(msg.key.remoteJidAlt)) participant = author }
+            else if (!sendActiveReceipts) type = 'inactive'
+            acked = true; await sendReceipt(msg.key.remoteJid, participant, [msg.key.id], type)
+            if (getHistoryMsg(msg.message)) await sendReceipt(jidNormalizedUser(msg.key.remoteJid), undefined, [msg.key.id], 'hist_sync')
+          } else { acked = true; await sendMessageAck(node); logger.debug({ key: msg.key }, 'processed newsletter message without receipts') }
+        }
+
+        cleanMessage(msg, authState.creds.me.id, authState.creds.me.lid)
+
+        if (!msg.key.fromMe) {
+          try {
+            const info = extractReportingInfoFromStanza(node)
+            if (info) {
+              const senderJid = msg.key.participant || author || msg.key.remoteJid
+              const contentType = msg.message ? getContentType(msg.message) : undefined
+              config.reportingInfoStore.add(senderJid, { stanzaId: info.stanzaId, timestamp: info.timestamp || Number(msg.messageTimestamp) || 0, reportingTag: info.reportingTag, text: extractMessageText(msg), pushName: msg.pushName || node.attrs?.notify || '', messageType: contentType === 'conversation' || contentType === 'extendedTextMessage' ? 'text' : contentType || 'text', fromJid: senderJid })
+            }
+          } catch (storeErr) { logger.warn({ err: storeErr, key: msg.key }, 'failed to store reporting_tag') }
+        }
+
+        await upsertMessage(msg, node.attrs.offline ? 'append' : 'notify')
+      })
+    } catch (error) {
+      const isClosed = error?.message?.includes('Connection Closed') || error?.output?.statusCode === 428
+      if (isClosed) logger.debug({ msg: error?.message }, 'Connection closed while handling message')
+      else logger.error({ error, stack: error?.stack, msg: error?.message || String(error), node: binaryNodeToString(node) }, 'error in handling message')
+      if (!acked) await sendMessageAck(node, NACK_REASONS.UnhandledError).catch(ackErr => logger.error({ ackErr }, 'failed to ack message after error'))
+    }
+  }
+
+  // ── handleCall ────────────────────────────────────────────────────────────
+
+  const handleCall = async (node) => {
+    const { attrs } = node
+    const [infoChild] = getAllBinaryNodeChildren(node)
+    if (!infoChild) throw new Boom('Missing call info in call node')
+    const status = getCallStatusFromNode(infoChild)
+    const callId = infoChild.attrs['call-id']
+    const from = infoChild.attrs.from || infoChild.attrs['call-creator']
+    const call = { chatId: attrs.from, from, callerPn: infoChild.attrs['caller_pn'], id: callId, date: new Date(+attrs.t * 1000), offline: !!attrs.offline, status }
+    if (status === 'offer') { call.isVideo = !!getBinaryNodeChild(infoChild, 'video'); call.isGroup = infoChild.attrs.type === 'group' || !!infoChild.attrs['group-jid']; call.groupJid = infoChild.attrs['group-jid']; await callOfferCache.set(call.id, call) }
+    const existingCall = await callOfferCache.get(call.id)
+    if (existingCall) { call.isVideo = existingCall.isVideo; call.isGroup = existingCall.isGroup; call.callerPn = call.callerPn || existingCall.callerPn }
+    if (['reject', 'accept', 'timeout', 'terminate'].includes(status)) await callOfferCache.del(call.id)
+    ev.emit('call', [call])
+    await sendMessageAck(node)
+  }
+
+  // ── handleBadAck ──────────────────────────────────────────────────────────
+
+  const handleBadAck = async ({ attrs }) => {
+    const key = { remoteJid: attrs.from, fromMe: true, id: attrs.id }
+    if (!attrs.error) return
+    const isReachoutTimelocked = attrs.error === String(NACK_REASONS.SenderReachoutTimelocked)
+    if (attrs.error === SERVER_ERROR_CODES.MessageAccountRestriction) {
+      logger.warn({ msgId: attrs.id, from: attrs.from }, 'error 463: account restricted or missing tctoken for contact')
+      const ackFrom = attrs.from
+      if (ackFrom && !inFlight463Recoveries.has(ackFrom)) {
+        inFlight463Recoveries.add(ackFrom)
+        void (async () => {
+          try {
+            const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
+            const tcStorageJid = await resolveTcTokenJid(ackFrom, getLIDForPN)
+            const issueToLid = sock.serverProps?.lidTrustedTokenIssueToLid ?? false
+            const issueJid = await resolveIssuanceJid(ackFrom, issueToLid, getLIDForPN, getPNForLID)
+            const result = await issuePrivacyTokens([issueJid], unixTimestampSeconds())
+            await storeTcTokensFromIqResult({ result, fallbackJid: tcStorageJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
+            logger.debug({ from: ackFrom }, 'completed 463 token recovery issuance')
+          } catch (err) { logger.debug({ from: ackFrom, err: err?.message }, 'failed 463 token recovery issuance') }
+          finally { inFlight463Recoveries.delete(ackFrom) }
+        })()
+      }
+    } else if (attrs.error === SERVER_ERROR_CODES.SmaxInvalid) {
+      logger.warn({ msgId: attrs.id, from: attrs.from }, 'smax-invalid (479): stale device session or malformed addressing')
+    } else if (isReachoutTimelocked) {
+      await fetchAccountReachoutTimelock().catch(err => logger.warn({ err }, 'failed to fetch reachout timelock'))
+      logger.warn({ attrs }, 'received error in ack')
+    } else {
+      logger.warn({ attrs }, 'received error in ack')
+    }
+    ev.emit('messages.update', [{ key, update: { status: WAMessageStatus.ERROR, messageStubParameters: isReachoutTimelocked ? [attrs.error, ACCOUNT_RESTRICTED_TEXT] : [attrs.error] } }])
+  }
+
+  // ── Offline node processor ────────────────────────────────────────────────
+
+  const processNodeWithBuffer = async (node, identifier, exec) => { ev.buffer(); await exec(node, false).catch(err => onUnexpectedError(err, identifier)); ev.flush() }
+  const yieldToEventLoop = () => new Promise(resolve => setImmediate(resolve))
+
+  const makeOfflineNodeProcessor = () => {
+    const nodeProcessorMap = new Map([['message', handleMessage], ['call', handleCall], ['receipt', handleReceipt], ['notification', handleNotification]])
+    const nodes = []
+    let isProcessing = false
+    const enqueue = (type, node) => {
+      nodes.push({ type, node })
+      if (isProcessing) return
+      isProcessing = true;
+      (async () => {
+        let processedInBatch = 0
+        while (nodes.length && ws.isOpen) {
+          const { type, node } = nodes.shift()
+          const processor = nodeProcessorMap.get(type)
+          if (!processor) { onUnexpectedError(new Error(`unknown offline node type: ${type}`), 'processing offline node'); continue }
+          await processor(node).catch(err => onUnexpectedError(err, `processing offline ${type}`))
+          if (++processedInBatch >= 10) { processedInBatch = 0; await yieldToEventLoop() }
+        }
+        isProcessing = false
+      })().catch(error => onUnexpectedError(error, 'processing offline nodes'))
+    }
+    return { enqueue }
+  }
+
+  const offlineNodeProcessor = makeOfflineNodeProcessor()
+
+  const processNode = async (type, node, identifier, exec) => {
+    const from = node.attrs.from
+    if (from && from !== S_WHATSAPP_NET && shouldIgnoreJid(from)) { await sendMessageAck(node, type === 'message' ? NACK_REASONS.UnhandledError : undefined); return }
+    if (node.attrs.offline) offlineNodeProcessor.enqueue(type, node)
+    else await processNodeWithBuffer(node, identifier, exec)
+  }
+
+  // ── WS event bindings ─────────────────────────────────────────────────────
+
+  ws.on('CB:message', async (node) => { await processNode('message', node, 'processing message', handleMessage) })
+  ws.on('CB:call', async (node) => { await processNode('call', node, 'handling call', handleCall) })
+  ws.on('CB:receipt', async (node) => { await processNode('receipt', node, 'handling receipt', handleReceipt) })
+  ws.on('CB:notification', async (node) => { await processNode('notification', node, 'handling notification', handleNotification) })
+  ws.on('CB:ack,class:message', (node) => { handleBadAck(node).catch(error => onUnexpectedError(error, 'handling bad ack')) })
+
+  ev.on('call', async ([call]) => {
+    if (!call) return
+    if (call.status === 'timeout' || (call.status === 'offer' && call.isGroup)) {
+      const msg = { key: { remoteJid: call.chatId, id: call.id, fromMe: false }, messageTimestamp: unixTimestampSeconds(call.date) }
+      if (call.status === 'timeout') msg.messageStubType = call.isGroup ? (call.isVideo ? WAMessageStubType.CALL_MISSED_GROUP_VIDEO : WAMessageStubType.CALL_MISSED_GROUP_VOICE) : (call.isVideo ? WAMessageStubType.CALL_MISSED_VIDEO : WAMessageStubType.CALL_MISSED_VOICE)
+      else msg.message = { call: { callKey: Buffer.from(call.id) } }
+      await upsertMessage(proto.WebMessageInfo.fromObject(msg), call.offline ? 'append' : 'notify')
+    }
+  })
+
+  // ── TC token pruning ──────────────────────────────────────────────────────
+
+  let lastTcTokenPruneTs = 0
+  const pruneExpiredTcTokens = async () => {
+    try {
+      await tcTokenIndexLoaded
+      const persisted = await readTcTokenIndex(authState.keys)
+      const allJids = new Set([...tcTokenKnownJids, ...persisted])
+      if (!allJids.size) return
+      const jids = [...allJids]
+      const allTokens = await authState.keys.get('tctoken', jids)
+      const writes = {}, survivors = new Set()
+      let mutated = 0
+      for (const jid of jids) {
+        const entry = allTokens[jid]
+        if (!entry) { mutated++; continue }
+        const hasPeerToken = !!entry.token?.length
+        const peerTokenExpired = hasPeerToken && isTcTokenExpired(entry.timestamp)
+        const hasSenderTs = entry.senderTimestamp !== undefined
+        const senderTsExpired = hasSenderTs && isTcTokenExpired(entry.senderTimestamp)
+        const keepPeer = hasPeerToken && !peerTokenExpired
+        const keepSender = hasSenderTs && !senderTsExpired
+        if (!keepPeer && !keepSender) { writes[jid] = null; mutated++ }
+        else if (peerTokenExpired && keepSender) { writes[jid] = { token: Buffer.alloc(0), senderTimestamp: entry.senderTimestamp }; survivors.add(jid); mutated++ }
+        else survivors.add(jid)
+      }
+      if (mutated === 0) return
+      await authState.keys.set({ tctoken: { ...writes, [TC_TOKEN_INDEX_KEY]: { token: Buffer.from(JSON.stringify([...survivors])) } } })
+      tcTokenKnownJids.clear(); for (const jid of survivors) tcTokenKnownJids.add(jid)
+      logger.debug({ mutated, remaining: survivors.size }, 'pruned expired tctokens')
+    } catch (err) { logger.warn({ err: err?.message }, 'failed to prune expired tctokens') }
+  }
+
+  ev.on('connection.update', ({ isOnline, connection }) => {
+    if (typeof isOnline !== 'undefined') { sendActiveReceipts = isOnline; logger.trace(`sendActiveReceipts set to "${sendActiveReceipts}"`) }
+    if (connection === 'close' && tcTokenIndexTimer) { clearTimeout(tcTokenIndexTimer); tcTokenIndexTimer = undefined; try { void Promise.resolve(flushTcTokenIndex()).catch(() => { }) } catch { } }
+    if (isOnline) { const now = Date.now(); if (now - lastTcTokenPruneTs >= 86_400_000) { lastTcTokenPruneTs = now; void pruneExpiredTcTokens() } }
+  })
+
+  registerSocketEndHandler(() => {
+    if (!config.msgRetryCounterCache && msgRetryCache.close) msgRetryCache.close()
+    if (!config.callOfferCache && callOfferCache.close) callOfferCache.close()
+    identityAssertDebounce.close()
+    sendActiveReceipts = false
+  })
+
+  return { ...sock, sendMessageAck, sendRetryRequest, rejectCall, offerCall, fetchMessageHistory, requestPlaceholderResend, requestContactRefresh, messageRetryManager, tcTokenIndexLoaded }
+}