release: develop → master 2026-06-06 (v2) — #509 + #510 + #511 + #512 (#513)

release: develop → master 2026-06-06 (v2) — #509 + #510 + #511 + #512 (#513)

Author: rsalcara

src/Signal/lid-mapping.ts

@@ -505,6 +505,53 @@ export class LIDMappingStore {
 		})
 	}
 
+	/**
+	 * Port of upstream PR #2614 (`fix: nest profile picture tctoken and avoid
+	 * usync on lookup`). Returns the LID for a PN ONLY if the mapping is
+	 * already known (memory cache or on-disk store). Never triggers a USync
+	 * lookup.
+	 *
+	 * Use this on hot paths where firing a USync just to opportunistically
+	 * attach metadata (e.g. profile-picture tctoken) is undesired — both
+	 * because the latency is wasted (the operation must still proceed if the
+	 * mapping is unknown) AND because USync-on-look-up is a behavioral
+	 * fingerprint WA Web / whatsmeow don't emit, so doing it makes our
+	 * traffic profile stand out and may serve as a ban signal.
+	 *
+	 * Thread safety: wrapped in `checkDestroyed()` + `trackOperation()` —
+	 * same contract every other public method on this store follows. Without
+	 * these, the async `keys.get()` could race with `destroy()` (UAF on the
+	 * key store) and a post-destroy call could silently return stale data.
+	 * (PR #510 review — addresses cubic / copilot P2.)
+	 */
+	async getKnownLIDForPN(pn: string): Promise<string | null> {
+		this.checkDestroyed()
+
+		return this.trackOperation(async () => {
+			if (!isAnyPnUser(pn)) return null
+
+			const decoded = jidDecode(pn)
+			if (!decoded) return null
+
+			const pnUser = decoded.user
+			let lidUser = this.mappingCache.get(`pn:${pnUser}`)
+			if (!lidUser) {
+				const stored = await this.keys.get('lid-mapping', [pnUser])
+				const storedLidUser = stored[pnUser]
+				if (typeof storedLidUser === 'string' && storedLidUser) {
+					lidUser = storedLidUser
+					this.mappingCache.set(`pn:${pnUser}`, lidUser)
+					this.mappingCache.set(`lid:${lidUser}`, pnUser)
+				}
+			}
+
+			if (!lidUser) return null
+
+			const pnDevice = decoded.device !== undefined ? decoded.device : 0
+			return `${lidUser}${pnDevice ? `:${pnDevice}` : ''}@${decoded.server === 'hosted' ? 'hosted.lid' : 'lid'}`
+		})
+	}
+
 	/**
 	 * Get LIDs for multiple PNs - Optimized batch operation
 	 *

src/Socket/chats.ts

@@ -55,7 +55,7 @@ import {
 } from '../Utils'
 import { makeKeyedMutex, makeMutex } from '../Utils/make-mutex'
 import processMessage from '../Utils/process-message'
-import { buildTcTokenFromJid } from '../Utils/tc-token-utils'
+import { buildTcTokenFromJid, buildTcTokenNode } from '../Utils/tc-token-utils'
 import {
 	type BinaryNode,
 	getBinaryNodeChild,
@@ -96,6 +96,14 @@ export const makeChatsSocket = (config: SocketConfig) => {
 	} = sock
 
 	const getLIDForPN = signalRepository.lidMapping.getLIDForPN.bind(signalRepository.lidMapping)
+	/**
+	 * Local-only LID resolver (port of upstream PR #2614). Use on
+	 * profile-picture / similar paths where we OPPORTUNISTICALLY attach
+	 * metadata: a USync miss should NOT bubble out as a network round-trip
+	 * because that traffic profile diverges from WA Web / whatsmeow and
+	 * smells like a custom client.
+	 */
+	const getKnownLIDForPN = signalRepository.lidMapping.getKnownLIDForPN.bind(signalRepository.lidMapping)
 
 	let privacySettings: { [_: string]: string } | undefined
 
@@ -132,7 +140,15 @@ export const makeChatsSocket = (config: SocketConfig) => {
 		config.placeholderResendCache ||
 		(new NodeCache<number>({
 			stdTTL: DEFAULT_CACHE_TTLS.MSG_RETRY, // 1 hour
-			useClones: false
+			useClones: false,
+			// Audit memory — this is the cache instantiation that REALLY
+			// runs in the standard socket chain (chats is the base; it
+			// mutates `config.placeholderResendCache` so the duplicated
+			// instantiation in messages-recv.ts with the same cap never
+			// fires). Without `maxKeys`, the NodeCache TTL of 1h plus
+			// re-extend-on-set means it grows unbounded under a stream of
+			// unique-id placeholder retries.
+			maxKeys: DEFAULT_CACHE_MAX_KEYS.PLACEHOLDER_RESEND
 		}) as CacheStore)
 
 	if (!config.placeholderResendCache) {
@@ -776,43 +792,88 @@ export const makeChatsSocket = (config: SocketConfig) => {
 	)
 
 	/**
-	 * fetch the profile picture of a user/group
-	 * type = "preview" for a low res picture
-	 * type = "image for the high res picture"
+	 * Fetch the profile picture URL of a user/group.
+	 *
+	 * `type`:        "preview" for a low-res picture, "image" for the high-res picture.
+	 * `existingId`:  the `id` of the last known picture for this JID. If supplied AND the
+	 *                picture has not changed, the server responds with a `304`-style empty
+	 *                result (sentinel for "use cached URL") instead of returning a fresh URL.
+	 *                Saves a CDN re-fetch per refresh — matches WA Web `pictureId` and
+	 *                whatsmeow `ExistingID`.
+	 * `invite`:      group-invite code. Allows fetching a group's picture without joining,
+	 *                used by the "preview before accepting invite" flow. Mutually exclusive
+	 *                with `tctoken` (server doesn't require it for invite-code lookups).
+	 * `personaId`:   Meta-AI bot persona id. Required to fetch the picture of an AI persona.
+	 * `commonGid`:   a group jid both parties belong to. Required when the target's privacy
+	 *                is set to "My contacts" and we are NOT in their contacts but share a
+	 *                group — without it the server returns 401/403. Matches WA Web.
+	 *
+	 * Stanza shape (matches WA Web `WASmaxOutProfilePictureGetRequest` + whatsmeow):
+	 *
+	 *   <iq xmlns="w:profile:picture" type="get" target="{jid}" to="s.whatsapp.net">
+	 *     <picture type="..." query="url" [id] [invite] [persona_id] [common_gid]>
+	 *       [<tctoken>...</tctoken>]   ← nested CHILD (not sibling)
+	 *     </picture>
+	 *   </iq>
 	 */
-	const profilePictureUrl = async (jid: string, type: 'preview' | 'image' = 'preview', timeoutMs?: number) => {
-		const baseContent: BinaryNode[] = [{ tag: 'picture', attrs: { type, query: 'url' } }]
-
-		// WA Web only includes tctoken for user JIDs (not groups/newsletters)
-		// and never for own profile pic (Chat model for self has no tcToken).
-		// Including tctoken for own JID causes the server to never respond.
+	const profilePictureUrl = async (
+		jid: string,
+		type: 'preview' | 'image' = 'preview',
+		timeoutMs?: number,
+		opts?: {
+			existingId?: string
+			invite?: string
+			personaId?: string
+			commonGid?: string
+		}
+	) => {
 		const normalizedJid = jidNormalizedUser(jid)
 		const isUserJid = isAnyPnUser(normalizedJid) || isAnyLidUser(normalizedJid)
 		const me = authState.creds.me
 		const isSelf =
 			me && (normalizedJid === jidNormalizedUser(me.id) || (me.lid && normalizedJid === jidNormalizedUser(me.lid)))
-		let content: BinaryNode[] | undefined = baseContent
 
-		if (isUserJid && !isSelf) {
-			content = await buildTcTokenFromJid({
+		// Build the <picture> attrs — include only the fields the caller supplied,
+		// so unset ones map to DROP_ATTR (matching WA Web's OPTIONAL serializer behavior).
+		const pictureAttrs: { [k: string]: string } = { type, query: 'url' }
+		if (opts?.existingId) pictureAttrs.id = opts.existingId
+		if (opts?.invite) pictureAttrs.invite = opts.invite
+		if (opts?.personaId) pictureAttrs.persona_id = opts.personaId
+		if (opts?.commonGid) pictureAttrs.common_gid = opts.commonGid
+
+		const pictureNode: BinaryNode = { tag: 'picture', attrs: pictureAttrs }
+
+		// Attach tctoken (if known) as a CHILD of <picture>. Match WA Web
+		// (WASmaxOutProfilePictureTCTokenMixin) and whatsmeow (pictureContent).
+		// WA Web only includes tctoken for user JIDs (not groups/newsletters)
+		// and never for own profile pic — including it for self causes the
+		// server to never respond. Invite-code lookups also skip the token
+		// (the invite IS the authorization).
+		if (isUserJid && !isSelf && !opts?.invite) {
+			const tctokenNode = await buildTcTokenNode({
 				authState,
 				jid: normalizedJid,
-				baseContent,
-				getLIDForPN
+				// Port of upstream PR #2614: never fire USync from the profile-picture
+				// path. If the LID mapping is unknown we send the IQ without the
+				// tctoken and let the server tell us (vs. doing a USync round trip
+				// that fingerprints us as non-WA-Web).
+				getLIDForPN: getKnownLIDForPN
 			})
+			if (tctokenNode) {
+				pictureNode.content = [tctokenNode]
+			}
 		}
 
-		jid = normalizedJid
 		const result = await query(
 			{
 				tag: 'iq',
 				attrs: {
-					target: jid,
+					target: normalizedJid,
 					to: S_WHATSAPP_NET,
 					type: 'get',
 					xmlns: 'w:profile:picture'
 				},
-				content
+				content: [pictureNode]
 			},
 			timeoutMs
 		)

src/Socket/messages-recv.ts

@@ -2236,8 +2236,19 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 
 				if (updatedDevices.length === 0) {
 					await userDevicesCache?.del(user)
-				} else {
-					await userDevicesCache?.set(user, updatedDevices)
+				} else if (userDevicesCache) {
+					// PR #513 review (chatgpt-codex P2): mirror the ECACHEFULL
+					// handling already in place for `userDevicesCache.set` in
+					// messages-send.ts. With the `maxKeys` cap added in PR
+					// #509, `@cacheable/node-cache` throws ECACHEFULL when
+					// `keyCount() + 1 > maxKeys` — and that check is hit even
+					// for an UPDATE of an already-cached key when the cache
+					// is at capacity, because the underlying `set` doesn't
+					// short-circuit on existing-key writes. `safeCacheSet`
+					// swallows the throw with a debug log; the durable USync
+					// state is unaffected (next message-send will re-fetch
+					// via `getUSyncDevices`, same fallback semantics).
+					await safeCacheSet(userDevicesCache, user, updatedDevices, logger, 'userDevicesCache')
 				}
 			}
 		})

src/Socket/messages-send.ts

@@ -2,7 +2,7 @@ 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, URL_REGEX, WA_DEFAULT_EPHEMERAL } from '../Defaults'
+import { DEFAULT_CACHE_MAX_KEYS, DEFAULT_CACHE_TTLS, URL_REGEX, WA_DEFAULT_EPHEMERAL } from '../Defaults'
 import type {
 	AlbumMediaItem,
 	AlbumMediaResult,
@@ -40,6 +40,7 @@ import {
 	normalizeMessageContent,
 	parseAndInjectE2ESessions,
 	runDetached,
+	safeCacheSet,
 	unixTimestampSeconds
 } from '../Utils'
 import { logMessageSent, logTcToken } from '../Utils/baileys-logger'
@@ -198,7 +199,16 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 		config.userDevicesCache ||
 		new NodeCache<JidWithDevice[]>({
 			stdTTL: DEFAULT_CACHE_TTLS.USER_DEVICES, // 5 minutes
-			useClones: false
+			useClones: false,
+			// Audit memory — cap defined in DEFAULT_CACHE_MAX_KEYS but never
+			// applied here. NodeCache TTL re-extends on every `.set()`, so
+			// under sustained traffic the TTL never expires; only `maxKeys`
+			// provides a hard ceiling. Empirical Frida capture on WA Android
+			// 2.26.21.75 confirms each outbound group msg can lazy-discover
+			// a new device → in a gateway with 50 active groups × 100 members
+			// × 1.5 devices avg the cache hits ~7,500 entries (already over
+			// the intended 5,000 cap).
+			maxKeys: DEFAULT_CACHE_MAX_KEYS.USER_DEVICES
 		})
 	/** Serializes writes to userDevicesCache across USync refresh and device-notification handling. */
 	const devicesMutex = makeMutex()
@@ -525,12 +535,36 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 			}
 
 			await devicesMutex.mutex(async () => {
+				// Audit ECACHEFULL — @cacheable/node-cache throws "Cache max keys amount
+				// exceeded" when `maxKeys` is reached (instead of LRU-evicting). For
+				// `mset` we fall back to a per-key path on ECACHEFULL so partial writes
+				// don't surface as send failures; for `.set` we route through
+				// `safeCacheSet` which already swallows ECACHEFULL with a debug log.
+				// Either way, durable state is unaffected — a cache miss next round
+				// triggers a USync refresh, same as a TTL-expired entry.
 				if (userDevicesCache.mset) {
-					// if the cache supports mset, we can set all devices in one go
-					await userDevicesCache.mset(Object.entries(deviceMap).map(([key, value]) => ({ key, value })))
+					try {
+						await userDevicesCache.mset(
+							Object.entries(deviceMap).map(([key, value]) => ({ key, value }))
+						)
+					} catch (err) {
+						const msg = (err as Error)?.message ?? ''
+						if (!msg.includes('max keys') && !msg.includes('ECACHEFULL')) throw err
+						logger.debug(
+							{ entries: Object.keys(deviceMap).length },
+							'userDevicesCache mset hit ECACHEFULL — falling back to per-key safeCacheSet'
+						)
+						for (const key in deviceMap) {
+							if (deviceMap[key]) {
+								await safeCacheSet(userDevicesCache, key, deviceMap[key], logger, 'userDevicesCache')
+							}
+						}
+					}
 				} else {
 					for (const key in deviceMap) {
-						if (deviceMap[key]) await userDevicesCache.set(key, deviceMap[key])
+						if (deviceMap[key]) {
+							await safeCacheSet(userDevicesCache, key, deviceMap[key], logger, 'userDevicesCache')
+						}
 					}
 				}
 			})