whalibmob 5.7.2 → 5.9.0

package/lib/Client.js

@@ -12,6 +12,14 @@ const { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, assert
 const { getDeviceConfig } = require('./DeviceConfig');
 const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts } = require('./Store');
 const { BinaryNode }      = require('./BinaryNode');
+const { AppStateStore, COLLECTIONS } = require('./appstate/AppStateStore');
+const AppStateSync  = require('./appstate/AppStateSync');
+const SyncdProto    = require('./appstate/SyncdProto');
+const AppMutations  = require('./appstate/Mutations');
+const {
+  GroupParticipantResult, GroupJoinRequest,
+  parseParticipantNodes, parseJoinRequestNode
+} = require('./GroupParticipant');
 
 // How many times a message may be re-sent in answer to retry receipts before
 // the client stops. Each resend can itself draw retries, so this is what keeps
@@ -28,6 +36,7 @@ const {
   decodeHistorySyncNotification,
   decodeAppStateSyncKeyShare,
   saveAppStateSyncKeys,
+  loadAppStateSyncKeys,
   HistorySyncType
 } = require('./HistorySyncHandler');
 
@@ -38,7 +47,7 @@ const STATUS_BROADCAST_JID = 'status@broadcast';
 const CALL_AUDIO_PREFIX = 'https://call.whatsapp.com/voice/';
 const CALL_VIDEO_PREFIX = 'https://call.whatsapp.com/video/';
 
-// whatsmeow's InviteLinkPrefix — the one prefix group invite codes are wrapped in.
+// The one prefix group invite codes are wrapped in.
 const INVITE_LINK_PREFIX = 'https://chat.whatsapp.com/';
 
 // The names privacy settings actually go by on the wire, and the friendly
@@ -233,7 +242,6 @@ class WhalibmobClient extends EventEmitter {
     // keyIds handed out by unresolved retries — never advertise one twice, or
     // the second sender's pkmsg arrives after the key was consumed and deleted.
     this._retryAdvertisedPreKeys = new Set();
-    this._appStateVersions = {};          // collectionName → version (int)
     this._sentMsgCache     = new Map();   // msgId → {plaintext, toJid, msgId, mediaType, options, recipientPhone}
     this._tcTokenStore            = null; // TcTokenStore — loaded in init()
     this._inFlightTcTokenIssuance = new Set(); // dedupe concurrent proactive issuePrivacyTokens per JID
@@ -305,6 +313,8 @@ class WhalibmobClient extends EventEmitter {
 
     const { TcTokenStore } = require('./messages/TcTokenStore');
     this._tcTokenStore = new TcTokenStore(tcTokenFile);
+    this._appState = new AppStateStore(
+      path.join(this._sessionDir, `${phoneNumber}.appState.json`));
 
     this._signal = SignalProtocol.fromStore(this._store, signalFile, skFile);
     this._devMgr = new DeviceManager(this);
@@ -491,6 +501,8 @@ class WhalibmobClient extends EventEmitter {
 
     const { TcTokenStore } = require('./messages/TcTokenStore');
     this._tcTokenStore = new TcTokenStore(tcTokenFile);
+    this._appState = new AppStateStore(
+      path.join(this._sessionDir, `${phoneNumber}.web.appState.json`));
 
     this._signal = SignalProtocol.fromStore(this._store, signalFile, skFile);
     this._devMgr = new DeviceManager(this);
@@ -944,7 +956,8 @@ class WhalibmobClient extends EventEmitter {
     // Every per-session file shares the phone number as its stem.
     const SUFFIXES = ['.json', '.signal.json', '.sk.json', '.tctoken.json',
                       '.device-cache.json', '.lid-mapping.json',
-                      '.lid-reverse-mapping.json', '.history.json', '.messages.json'];
+                      '.lid-reverse-mapping.json', '.history.json', '.messages.json',
+                      '.appState.json', '.appStateKeys.json'];
     const moved = [];
     for (const suffix of SUFFIXES) {
       const from = path.join(this._sessionDir, current + suffix);
@@ -1160,12 +1173,11 @@ class WhalibmobClient extends EventEmitter {
     }, [new BinaryNode('active', {}, null)]));
   }
 
-  // ── Feature 3 (part B): Handle <ib> dirty-state notifications ──────────────
+  // ── <ib> dirty-state notifications ────────────────────────────────────────
   //
-  // After login the server sends <ib><dirty type="account_sync"…/></ib> to
-  // tell the client that its app state is stale.  We respond with a sync IQ
-  // for each dirty collection.  We track the version number for each
-  // collection in _appStateVersions so we don't repeatedly request version 0.
+  // After login the server sends <ib><dirty type="account_sync"/></ib> to say
+  // our app state is behind. Each dirty type names what has moved on; the sync
+  // that follows asks for it from the version we last stored.
   _handleIb(node) {
     const children = Array.isArray(node.content) ? node.content : [];
 
@@ -1216,27 +1228,53 @@ class WhalibmobClient extends EventEmitter {
     }, [new BinaryNode('clean', attrs, null)]));
   }
 
+  /**
+   * Re-read every group we belong to, then acknowledge the dirty bit.
+   *
+   * Best effort on purpose: the bit has to be cleared either way, or the server
+   * announces the same change on every connection from now on.
+   */
+  _refreshGroupsAfterDirty(type) {
+    Promise.resolve()
+      .then(() => this.fetchAllGroups())
+      .then(groups => {
+        _whaDbg('[DBG] DIRTY groups — refreshed ' + (groups ? groups.length : 0) + ' group(s)');
+      })
+      .catch(err => {
+        _whaDbg('[DBG] DIRTY groups — refresh failed: ' + (err && err.message));
+      })
+      .then(() => this._cleanDirtyBits(type));
+  }
+
   _sendAppStateSyncForTypes(dirtyTypes) {
     if (!this._socket || !this._connected) return;
 
-    // Only these are valid WhatsApp app-state collections.
-    // Other dirty types (e.g. "groups") use different IQs and must be ignored here.
+    // "account_sync" means everything; the rest name one collection each.
+    // Anything not in here is a dirty bit that travels by some other route.
     const COLLECTION_MAP = {
-      account_sync:        ['critical_block', 'critical_unblock_low', 'regular_low', 'regular_high', 'regular'],
-      critical_block:      ['critical_block'],
-      critical_unblock_low:['critical_unblock_low'],
-      regular_low:         ['regular_low'],
-      regular_high:        ['regular_high'],
-      regular:             ['regular']
+      account_sync:         COLLECTIONS.slice(),
+      critical_block:       ['critical_block'],
+      critical_unblock_low: ['critical_unblock_low'],
+      regular_low:          ['regular_low'],
+      regular_high:         ['regular_high'],
+      regular:              ['regular']
     };
 
     const collections = new Set();
     for (const type of dirtyTypes) {
       const mapped = COLLECTION_MAP[type];
       if (!mapped) {
-        // "groups" is not an app-state collection, but it is still a dirty bit
-        // the server expects to be cleared. Ignoring it meant the server
-        // re-announced it on every single connection, forever.
+        if (type === 'groups') {
+          // The bit means something about our groups changed while we were
+          // away. Clearing it without looking leaves every cached group sitting
+          // on the membership and settings it had before we disconnected, so
+          // re-read them first and acknowledge after.
+          this._refreshGroupsAfterDirty(type);
+          continue;
+        }
+        // Not an app-state collection, but still a dirty bit the server expects
+        // to be cleared. Ignoring it meant the server re-announced it on every
+        // single connection, forever.
         _whaDbg('[DBG] DIRTY type=' + type + ' — not an app-state collection, clearing the bit');
         this._cleanDirtyBits(type);
         continue;
@@ -1245,41 +1283,381 @@ class WhalibmobClient extends EventEmitter {
     }
 
     if (collections.size === 0) return;
+    this.syncAppState([...collections]).catch(err => {
+      _whaDbg('[DBG] APP_STATE sync failed: ' + (err && err.message));
+    });
+  }
 
-    const id = this._genMsgId();
-    const collectionNodes = [...collections].map(name => {
-      const version = String(this._appStateVersions[name] || 0);
+  /**
+   * Pull app state down from the server and apply it.
+   *
+   * This is how everything that is not a message reaches a linked device:
+   * which chats are pinned, archived, muted or marked unread, which messages
+   * are starred, what your contacts are called. It is also the only way those
+   * changes travel *back* — see the chat methods further down, which write
+   * patches rather than mutating anything locally.
+   *
+   * A collection is asked for from the version we hold, and the server answers
+   * with the patches since then. From version 0 it sends a snapshot instead:
+   * the whole collection, which is also what we fall back to when the running
+   * hash stops agreeing with the server's.
+   *
+   * @param {string[]} [names]  collections to sync; all of them by default
+   * @param {object}   [opts]   { snapshot: true } to force a full re-read
+   * @returns {Promise<{applied: number, collections: object}>}
+   */
+  async syncAppState(names, opts) {
+    opts = opts || {};
+    if (!this._socket || !this._connected) throw new Error('Not connected');
+    if (!this._appState) throw new Error('No session — call init() first');
+
+    const wanted = (names && names.length ? names : COLLECTIONS)
+      .filter(n => COLLECTIONS.includes(n));
+    if (!wanted.length) return { applied: 0, collections: {} };
+
+    const keys = this._appStateKeys();
+    if (!Object.keys(keys).length) {
+      // The keys arrive from the primary device in an encrypted message. Until
+      // one has, there is nothing that can be decrypted and asking would only
+      // throw the patches away.
+      _whaDbg('[DBG] APP_STATE no sync keys yet — skipping');
+      return { applied: 0, collections: {}, waitingForKeys: true };
+    }
+
+    const nodes = wanted.map(name => {
+      const st = this._appState.get(name);
+      const wantSnapshot = !!opts.snapshot || !st.version;
       return new BinaryNode('collection', {
         name,
-        version,
-        return_snapshot: 'false'
+        version:         String(wantSnapshot ? 0 : st.version),
+        return_snapshot: wantSnapshot ? 'true' : 'false'
       }, null);
     });
 
-    _whaDbg('[DBG] SEND appStateSync IQ id=' + id + ' collections=' + [...collections].join(','));
-    this._socket.sendNode(new BinaryNode('iq', {
-      id,
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
       to:    's.whatsapp.net',
       type:  'set',
       xmlns: 'w:sync:app:state'
-    }, [new BinaryNode('sync', {}, collectionNodes)]));
-
-    // When the server replies, update our version numbers so future syncs
-    // request incremental patches rather than a full snapshot.
-    this._pendingIqs.set(id, (resp) => {
-      if (!resp || !Array.isArray(resp.content)) return;
-      const syncNode = findChild(resp, 'sync');
-      if (!syncNode || !Array.isArray(syncNode.content)) return;
-      for (const colNode of syncNode.content) {
-        if (!colNode || colNode.description !== 'collection') continue;
-        const colAttrs = colNode.attrs || {};
-        if (colAttrs.name && colAttrs.version !== undefined) {
-          this._appStateVersions[colAttrs.name] = parseInt(colAttrs.version, 10) || 0;
+    }, [new BinaryNode('sync', {}, nodes)]));
+
+    if (!resp) throw new Error('syncAppState: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('syncAppState: server rejected the request' +
+        (code ? ' (' + code + ')' : ''));
+    }
+
+    return this._applyAppStateResponse(resp, opts);
+  }
+
+  /**
+   * The sync keys the primary device has shared, keyed by base64 id.
+   *
+   * They are stored under their hex id but every reference on the wire is
+   * base64, so both spellings are returned and a lookup either way works.
+   */
+  _appStateKeys() {
+    if (!this._store || !this._store.phoneNumber) return {};
+    let raw;
+    try { raw = loadAppStateSyncKeys(this._sessionDir, this._store.phoneNumber) || {}; }
+    catch (_) { raw = {}; }
+    const out = {};
+    for (const [hexId, v] of Object.entries(raw)) {
+      out[hexId] = v;
+      try { out[Buffer.from(hexId, 'hex').toString('base64')] = v; } catch (_) {}
+    }
+    return out;
+  }
+
+  async _applyAppStateResponse(resp, opts) {
+    const syncNode = findChild(resp, 'sync');
+    const cols     = (syncNode && Array.isArray(syncNode.content))
+      ? syncNode.content.filter(n => n && n.description === 'collection') : [];
+
+    const keys    = this._appStateKeys();
+    const getKey  = (b64) => keys[b64] || null;
+    const summary = {};
+    let   applied = 0;
+    let   more    = [];
+
+    for (const col of cols) {
+      const name = col.attrs && col.attrs.name;
+      if (!name || !COLLECTIONS.includes(name)) continue;
+
+      const mutations = [];
+      const collect   = (m) => mutations.push(m);
+      let   result    = null;
+      let   snapshotted = false;
+
+      try {
+        const snapNode = findChild(col, 'snapshot');
+        if (snapNode && snapNode.content) {
+          const blob = await this._fetchAppStateBlob(
+            SyncdProto.decodeExternalBlobReference(getNodeContent(snapNode)));
+          const snap = SyncdProto.decodeSnapshot(blob);
+          result = AppStateSync.decodeSnapshot(name, snap, getKey, collect, true);
+          snapshotted = true;
+        } else {
+          const patchesNode = findChild(col, 'patches') || col;
+          const raw = (Array.isArray(patchesNode.content) ? patchesNode.content : [])
+            .filter(n => n && n.description === 'patch' && getNodeContent(n))
+            .map(n => SyncdProto.decodePatch(getNodeContent(n)));
+
+          // A patch too big to inline is moved into a CDN blob and referenced.
+          for (const p of raw) {
+            if (!p.externalMutations) continue;
+            const blob = await this._fetchAppStateBlob(p.externalMutations);
+            p.mutations = p.mutations.concat(SyncdProto.decodeMutations(blob));
+          }
+          if (!raw.length) { summary[name] = { patches: 0, applied: 0 }; continue; }
+          result = AppStateSync.decodePatches(
+            name, raw, this._appState.get(name), getKey, collect, true);
+        }
+      } catch (err) {
+        if (err && err.isMissingKey) {
+          // Nothing can be read until the primary shares that key. Leave the
+          // collection where it is so the next sync picks up from here.
+          _whaDbg('[DBG] APP_STATE ' + name + ' waiting for key ' + err.keyId);
+          summary[name] = { waitingForKey: err.keyId };
+          this.emit('app_state_key_missing', { collection: name, keyId: err.keyId });
+          continue;
         }
+        throw err;
       }
+
+      // Our hash and the server's have parted company. Every patch after the
+      // break would be applied to the wrong base, so throw our copy away and
+      // ask for the whole collection instead — once. If the snapshot itself
+      // does not verify, keep what we could read and say so.
+      if (result.macFailed && !snapshotted && !opts.snapshot) {
+        _whaDbg('[DBG] APP_STATE ' + name + ' hash mismatch — refetching as snapshot');
+        this._appState.reset(name);
+        more.push(name);
+        continue;
+      }
+
+      this._appState.set(name, result.state);
+      applied += this._applyAppStateMutations(name, mutations);
+      summary[name] = {
+        version: result.state.version,
+        applied: mutations.length,
+        skipped: result.skipped || 0,
+        snapshot: snapshotted,
+        macOk: snapshotted ? result.macOk !== false : !result.macFailed
+      };
+
+      if (col.attrs && col.attrs.has_more_patches === 'true') more.push(name);
+    }
+
+    if (more.length && !opts._retried) {
+      const again = await this.syncAppState(more, Object.assign({}, opts, { _retried: true }));
+      applied += again.applied;
+      Object.assign(summary, again.collections);
+    }
+
+    this.emit('app_state_sync', { collections: summary, applied });
+    return { applied, collections: summary };
+  }
+
+  /** Fetch and decrypt an app-state blob the server pushed to the CDN. */
+  async _fetchAppStateBlob(ref) {
+    if (!ref || !ref.mediaKey) throw new Error('app state blob reference is incomplete');
+    const { downloadMedia, resolveMediaUrl } = require('./MediaService');
+    const url = resolveMediaUrl(null, ref.directPath);
+    if (!url) throw new Error('app state blob has no directPath');
+    return downloadMedia(url, ref.mediaKey, 'WhatsApp App State Keys', {
+      web: this._mode === 'web'
     });
   }
 
+  /**
+   * Fold decoded mutations into the local view and announce them.
+   *
+   * These are changes made somewhere else — on the phone, or on another linked
+   * device — so they are applied without being echoed back as patches of our
+   * own, which would bounce between devices forever.
+   */
+  _applyAppStateMutations(collection, mutations) {
+    let count = 0;
+    for (const m of mutations) {
+      const what = AppMutations.describeIndex(m.index);
+      if (!what) continue;
+      const removed = m.operation === SyncdProto.REMOVE;
+      const a       = m.action || {};
+      const jid     = what.jid ? makeJid(what.jid) : null;
+
+      switch (what.kind) {
+        case 'pin': {
+          const pinned = !removed && !!(a.pinAction && a.pinAction.pinned);
+          this._getChatState(jid).pinnedAt = pinned ? (a.timestamp ? Math.floor(a.timestamp / 1000) : Math.floor(Date.now() / 1000)) : 0;
+          this.emit('chat_pinned', { jid, pinned, remote: true });
+          break;
+        }
+        case 'archive': {
+          const archived = !removed && !!(a.archiveChatAction && a.archiveChatAction.archived);
+          this._getChatState(jid).archived = archived;
+          this.emit('chat_archived', { jid, archived, remote: true });
+          break;
+        }
+        case 'mute': {
+          const mute    = a.muteAction || {};
+          const muted   = !removed && !!mute.muted;
+          const chat    = this._getChatState(jid);
+          chat.muted       = muted;
+          chat.muteUntilMs = muted ? (Number(mute.muteEndTimestamp) || -1) : 0;
+          this.emit('chat_muted', { jid, muted, until: chat.muteUntilMs, remote: true });
+          break;
+        }
+        case 'markRead': {
+          const read = !removed && !!(a.markChatAsReadAction && a.markChatAsReadAction.read);
+          this._getChatState(jid).markedAsUnread = !read;
+          this.emit('chat_read', { jid, read, remote: true });
+          break;
+        }
+        case 'star': {
+          const starred = !removed && !!(a.starAction && a.starAction.starred);
+          if (!this._starredMessages) this._starredMessages = new Set();
+          const key = jid + ':' + what.msgId;
+          if (starred) this._starredMessages.add(key); else this._starredMessages.delete(key);
+          this.emit('message_starred', {
+            msgId: what.msgId, chatJid: jid, starred, fromMe: what.fromMe, remote: true
+          });
+          break;
+        }
+        case 'contact': {
+          const c = a.contactAction || {};
+          this.emit('contact_update', {
+            jid,
+            name:      c.fullName || c.firstName || null,
+            firstName: c.firstName || null,
+            lid:       c.lidJid || null,
+            username:  c.username || null,
+            removed,
+            remote:    true
+          });
+          break;
+        }
+        case 'pushName': {
+          const name = (a.pushNameSetting && a.pushNameSetting.name) || null;
+          if (name && this._store) this._store.pushName = name;
+          this.emit('push_name_update', { name, remote: true });
+          break;
+        }
+        case 'clear':
+        case 'delete':
+          this.emit('chat_removed', { jid, kind: what.kind, remote: true });
+          break;
+        default:
+          // Something the server tracks that this library does not model yet.
+          // Reported rather than dropped, so it is visible that it happened.
+          this.emit('app_state_mutation', {
+            collection, index: m.index, action: a, removed
+          });
+          break;
+      }
+      count++;
+    }
+    return count;
+  }
+
+  /**
+   * Whether this session can write app state at all.
+   *
+   * App-state keys travel one way: the primary device shares them with the
+   * companions it has linked. A companion always gets one. A session that
+   * registered over SMS *is* the primary, so unless it has linked a companion
+   * of its own there is no key in existence and nothing to sign a patch with.
+   */
+  canSyncAppState() {
+    return !!this._newestAppStateKey(this._appStateKeys());
+  }
+
+  /**
+   * Write a change into app state when that is possible, and fall back to
+   * whatever the connection can do otherwise.
+   *
+   * Without this, every chat setting would throw on an SMS session — which is
+   * exactly the connection least able to do anything about it, since the key it
+   * is being asked for is one only it could ever create.
+   *
+   * @returns {Promise<boolean>} whether the change was written to app state,
+   *                             and so will reach other devices
+   */
+  async _appStatePatchOrFallback(desc, fallback) {
+    if (this.canSyncAppState()) {
+      await this._sendAppStatePatch(desc);
+      return true;
+    }
+    if (typeof fallback === 'function') await fallback();
+    return false;
+  }
+
+  /**
+   * Write one change into app state, so it reaches the phone and every other
+   * linked device.
+   *
+   * The local view is updated from the same description that goes on the wire,
+   * so what a caller sees immediately is what the other devices will see.
+   */
+  async _sendAppStatePatch(desc) {
+    if (!this._socket || !this._connected) throw new Error('Not connected');
+    if (!this._appState) throw new Error('No session — call init() first');
+
+    const chosen = this._newestAppStateKey(this._appStateKeys());
+    if (!chosen) {
+      throw new Error('cannot write app state yet: the primary device has not ' +
+        'shared a sync key with this session');
+    }
+
+    const state = this._appState.get(desc.name);
+    const { patch, state: next } = AppStateSync.buildPatch(
+      desc, chosen.id, chosen.keyData, state);
+
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'set',
+      xmlns: 'w:sync:app:state'
+    }, [
+      new BinaryNode('sync', {}, [
+        new BinaryNode('collection', {
+          name:            desc.name,
+          version:         String(next.version - 1),
+          return_snapshot: 'false'
+        }, [new BinaryNode('patch', {}, patch)])
+      ])
+    ]));
+
+    if (!resp) throw new Error('app state patch: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      // The server did not take it, so our state must not move on either.
+      throw new Error('app state patch rejected by server' + (code ? ' (' + code + ')' : ''));
+    }
+
+    this._appState.set(desc.name, next);
+    return next.version;
+  }
+
+  // The most recently shared key, which is the one to sign new patches with.
+  //
+  // Both spellings of every id are in the map, so the hex ones are passed over
+  // — a patch names its key in base64.
+  _newestAppStateKey(keys) {
+    let best = null;
+    for (const [id, v] of Object.entries(keys || {})) {
+      if (!v || !v.keyData) continue;
+      if (/^[0-9a-f]+$/i.test(id)) continue;
+      if (!best || (v.timestamp || 0) > (best.timestamp || 0)) {
+        best = { id, keyData: v.keyData, timestamp: v.timestamp || 0 };
+      }
+    }
+    return best;
+  }
+
   _onClose() {
     this._connected = false;
     this._stopTimers();
@@ -1904,8 +2282,43 @@ class WhalibmobClient extends EventEmitter {
     const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
     const norm = normalizeJidForTcToken(jid);
     if (norm.endsWith('@lid')) return norm;
-    const lidUser = this._pnToLid && this._pnToLid.get(norm.split('@')[0]);
-    return lidUser ? lidUser + '@lid' : norm;
+
+    const pnUser = norm.split('@')[0];
+    let lidUser = this._pnToLid && this._pnToLid.get(pnUser);
+
+    // The in-memory map starts empty and is filled by usync and by incoming
+    // messages, so a send early in a process — or one that hits a warm device
+    // cache and never runs usync — could find nothing and fall back to the
+    // phone JID. The mapping is on disk in the Signal store either way, which
+    // is the same place whatsmeow reads it from, so consult that before giving
+    // up. The consequence of not doing so is not cosmetic: the lookup lands on
+    // a key with no token while a live one sits under the LID, and the message
+    // goes out without one.
+    if (!lidUser) {
+      const store = this._signal && this._signal.store;
+      const persisted = store && typeof store.getLidMappings === 'function'
+        ? store.getLidMappings() : null;
+      const fromDisk = persisted && persisted[pnUser];
+      if (fromDisk) {
+        lidUser = String(fromDisk);
+        if (this._pnToLid) this._pnToLid.set(pnUser, lidUser);
+        if (this._lidToPn) this._lidToPn.set(lidUser, pnUser);
+        _whaDbg('[DBG] TCTOKEN_LID_FROM_DISK pn=' + pnUser + ' lid=' + lidUser);
+      }
+    }
+
+    if (!lidUser) return norm;
+
+    const lidJid = lidUser + '@lid';
+
+    // Anything already filed under the phone JID belongs with the LID entry.
+    // Left split, the two halves each hold part of the state and neither is
+    // complete. Cheap when there is nothing to move, which is the usual case.
+    if (this._tcTokenStore && this._tcTokenStore.mergeEntry(norm, lidJid)) {
+      _whaDbg('[DBG] TCTOKEN_MERGED ' + norm + ' → ' + lidJid);
+    }
+
+    return lidJid;
   }
 
   // The JID a token is *issued* to, which is not the JID it is *stored* under.
@@ -2613,7 +3026,20 @@ class WhalibmobClient extends EventEmitter {
           if (this._signal && this._signal.store && this._signal.store.setLidMapping)
             this._signal.store.setLidMapping(pnUser, lidUser);
         }
-        return { jid: pJid, role: pRole };
+        return {
+          jid:  pJid,
+          role: pRole,
+          // Both address families, whichever way round the server named them,
+          // so a caller does not have to reach into the LID maps to find out
+          // who a participant is.
+          phoneNumber:  pJid.endsWith('@lid') ? pPhone : pJid,
+          lid:          pJid.endsWith('@lid') ? pJid   : pLid,
+          displayName:  n.attrs.display_name ? String(n.attrs.display_name) : null,
+          username:     n.attrs.participant_username ? String(n.attrs.participant_username)
+                      : n.attrs.username ? String(n.attrs.username) : null,
+          isAdmin:      pRole === 'admin' || pRole === 'superadmin',
+          isSuperAdmin: pRole === 'superadmin'
+        };
       });
 
     // description — the id is the "topic id" the server wants echoed back as
@@ -2633,6 +3059,13 @@ class WhalibmobClient extends EventEmitter {
       if (buf) description = buf.toString('utf8');
     }
 
+    const descriptionBy = (descNode && descNode.attrs && descNode.attrs.participant)
+      ? toNonAdJid(String(descNode.attrs.participant)) : null;
+    const descriptionByPn = (descNode && descNode.attrs && descNode.attrs.participant_pn)
+      ? toNonAdJid(String(descNode.attrs.participant_pn)) : null;
+    const descriptionTime = (descNode && descNode.attrs)
+      ? parseInt(descNode.attrs.t, 10) || 0 : 0;
+
     // ephemeral
     const ephNode = children.find(n => n && n.description === 'ephemeral');
     const ephemeral = ephNode && ephNode.attrs ? parseInt(ephNode.attrs.expiration, 10) || 0 : 0;
@@ -2641,6 +3074,22 @@ class WhalibmobClient extends EventEmitter {
     const announce = children.some(n => n && n.description === 'announcement');
     const restrict = children.some(n => n && n.description === 'locked');
 
+    // The rest of the flags the server reports. These used to be dropped, which
+    // meant a group's join-approval and member-add settings could be written but
+    // never read back — changing one and then asking for the metadata reported
+    // nothing at all about it.
+    const joinApprovalMode = children.some(n => n && n.description === 'membership_approval_mode');
+    const parentNode       = children.find(n => n && n.description === 'parent');
+    const linkedParentNode = children.find(n => n && n.description === 'linked_parent');
+    const memberAddNode    = children.find(n => n && n.description === 'member_add_mode');
+    const memberAddBuf     = memberAddNode ? getNodeContent(memberAddNode) : null;
+    const memberAddMode    = memberAddBuf ? memberAddBuf.toString('utf8') : null;
+    // An incognito group hides members' phone numbers from each other, and a
+    // suspended one has been taken down — both are things a caller has to be
+    // able to see rather than discover by having every send refused.
+    const isIncognito      = children.some(n => n && n.description === 'incognito');
+    const isSuspended      = children.some(n => n && n.description === 'suspended');
+
     const groupId = a.id || '';
     const jid = groupId.includes('@') ? groupId : groupId + '@g.us';
 
@@ -2660,9 +3109,41 @@ class WhalibmobClient extends EventEmitter {
       subjectBy:  a.s_o || null,
       description,
       descriptionId,
+      descriptionBy,
+      descriptionByPn,
+      descriptionTime,
       ephemeral,
       onlyAdminsSend: announce,
       onlyAdminsEdit: restrict,
+      // Whether new members have to be waved through by an admin.
+      joinApprovalMode,
+      // 'admin_add' | 'all_member_add' | null when the server did not say.
+      memberAddMode,
+      // A community's own node, and the community a plain group belongs to.
+      isCommunity: !!parentNode,
+      // How a community waves its incoming sub-group members through by default.
+      defaultMembershipApprovalMode:
+        (parentNode && parentNode.attrs && parentNode.attrs.default_membership_approval_mode)
+          ? String(parentNode.attrs.default_membership_approval_mode) : null,
+      isCommunityAnnounce: children.some(n => n && n.description === 'default_sub_group'),
+      linkedParent: (linkedParentNode && linkedParentNode.attrs && linkedParentNode.attrs.jid)
+        ? String(linkedParentNode.attrs.jid) : null,
+      isIncognito,
+      isSuspended,
+      // The phone-number and username forms of the two people named in the
+      // header, when the server sends them alongside the addresses it used.
+      creatorPn:        a.creator_pn ? toNonAdJid(String(a.creator_pn)) : null,
+      creatorUsername:  a.creator_username || null,
+      creatorCountry:   a.creator_country_code || null,
+      subjectByPn:      a.s_o_pn ? toNonAdJid(String(a.s_o_pn)) : null,
+      subjectByUsername: a.s_o_username || null,
+      notify:           a.notify || null,
+      // Version stamps the server bumps whenever the participant list or the
+      // announce flag changes; a cache can compare them instead of re-reading.
+      participantVersion: a.p_v_id || null,
+      announceVersion:    a.a_v_id || null,
+      // The server's own count, which can exceed the participant list it sent.
+      size: a.size ? parseInt(a.size, 10) || participants.length : participants.length,
       addressingMode,
       participants
     };
@@ -3650,6 +4131,49 @@ class WhalibmobClient extends EventEmitter {
     return httpGetBuffer(info.url, { web: this._mode === 'web' });
   }
 
+  // Download and decrypt the media on a received message.
+  //
+  // Pass the decoded message straight through — `msg.decoded` from a `message`
+  // event, or the object itself:
+  //
+  //   client.on('message', async (msg) => {
+  //     if (msg.decoded && msg.decoded.mediaKey) {
+  //       fs.writeFileSync('out.jpg', await client.downloadMedia(msg.decoded))
+  //     }
+  //   })
+  //
+  // The CDN applies the same browser check on the way down as on the way up, so
+  // a companion has to identify itself as one here too. Doing it by hand means
+  // knowing that, and knowing which key name each media type derives from — get
+  // either wrong and the download is refused or the decryption produces garbage.
+  //
+  // A file already saved from a previous run can be verified against the
+  // message with { verify: true }, which checks fileEncSha256 before decrypting.
+  async downloadMedia(decoded, opts) {
+    opts = opts || {};
+    const d = (decoded && decoded.decoded) ? decoded.decoded : decoded;
+    if (!d || !d.type) throw new Error('downloadMedia: a decoded message is required');
+    if (!d.mediaKey)   throw new Error('downloadMedia: this message carries no media');
+
+
+    // A voice note is an audio message with PTT set, and a GIF a video with the
+    // playback flag — both derive from the plain type's keys.
+    const KEY_NAME = {
+      image: 'image', video: 'video', audio: 'audio', voice: 'ptt',
+      ptt: 'ptt', document: 'document', sticker: 'sticker', gif: 'gif'
+    };
+    const { downloadMedia, getMediaKeyName, resolveMediaUrl } = require('./MediaService');
+    const url = resolveMediaUrl(d.url, d.directPath);
+    if (!url) throw new Error('downloadMedia: the message has no CDN location');
+    const keyName = getMediaKeyName(KEY_NAME[d.type] || d.type);
+    if (!keyName) throw new Error('downloadMedia: unsupported media type "' + d.type + '"');
+
+    return downloadMedia(url, d.mediaKey, keyName, {
+      web:           this._mode === 'web',
+      fileEncSha256: opts.verify ? d.fileEncSha256 : undefined
+    });
+  }
+
   // Parse the <list> a blocklist query or update comes back with.
   //
   // whatsmeow's parseBlocklist walks every child and takes its jid, without
@@ -4359,69 +4883,68 @@ class WhalibmobClient extends EventEmitter {
   //              blockContact, unblockContact, changeEphemeralTimer
   // ──────────────────────────────────────────────────────────────────────────
 
-  // Mark entire chat as read — sends IQ to server (xmlns: 'w', count: '-1')
+  // Clears the unread badge on a chat. This is the chat's own read flag — to
+  // send read receipts for particular messages, use markRead().
   async markChatRead(jid) {
     const jidFull = makeJid(jid);
-    const id = this._genMsgId();
-    const node = new BinaryNode('iq', {
-      id,
-      to:    's.whatsapp.net',
-      type:  'set',
-      xmlns: 'w'
-    }, [
-      new BinaryNode('read', { jid: jidFull, count: '-1', index: '0', owner: 'false' }, null)
-    ]);
-    const chat = this._getChatState(jid);
-    chat.markedAsUnread = false;
-    this.emit('chat_read', { jid: jidFull, read: true });
-    return this._sendIq(node);
-  }
-
-  // Mark entire chat as unread — local state only (no WhatsApp server equivalent for mobile)
-  markChatUnread(jid) {
-    const chat = this._getChatState(makeJid(jid));
-    chat.markedAsUnread = true;
-    this.emit('chat_read', { jid: makeJid(jid), read: false });
+    const synced  = await this._appStatePatchOrFallback(
+      AppMutations.markReadPatch(jidFull, true),
+      () => this._sendIq(new BinaryNode('iq', {
+        id: this._genMsgId(), to: 's.whatsapp.net', type: 'set', xmlns: 'w'
+      }, [new BinaryNode('read',
+        { jid: jidFull, count: '-1', index: '0', owner: 'false' }, null)])));
+    this._getChatState(jidFull).markedAsUnread = false;
+    this.emit('chat_read', { jid: jidFull, read: true, synced });
+    return synced;
+  }
+
+  async markChatUnread(jid) {
+    const jidFull = makeJid(jid);
+    const synced  = await this._appStatePatchOrFallback(
+      AppMutations.markReadPatch(jidFull, false));
+    this._getChatState(jidFull).markedAsUnread = true;
+    this.emit('chat_read', { jid: jidFull, read: false, synced });
+    return synced;
   }
 
-  // Mute a chat — sends IQ to server (xmlns: 'w:web')
-  // durationMs: milliseconds, 0 or negative = mute indefinitely
+  // durationMs is how long from now to stay muted; 0 or omitted means until
+  // it is unmuted by hand. The wire carries an absolute end in milliseconds.
   async muteChat(jid, durationMs) {
-    const jidFull  = makeJid(jid);
-    const muteEnd  = (durationMs && durationMs > 0)
-      ? Math.floor((Date.now() + durationMs) / 1000)
-      : 0;
-    const id = this._genMsgId();
-    const attrs = { jid: jidFull, add: '1' };
-    if (muteEnd > 0) attrs.t = String(muteEnd);
-    const node = new BinaryNode('iq', {
-      id,
-      to:    's.whatsapp.net',
-      type:  'set',
-      xmlns: 'w:web'
-    }, [new BinaryNode('mute', attrs, null)]);
-    const chat = this._getChatState(jid);
+    const jidFull = makeJid(jid);
+    const endMs   = (durationMs && durationMs > 0) ? Date.now() + durationMs : 0;
+    const synced  = await this._appStatePatchOrFallback(
+      AppMutations.mutePatch(jidFull, endMs || 1),
+      () => this._muteIq(jidFull, endMs ? Math.floor(endMs / 1000) : 0));
+    const chat = this._getChatState(jidFull);
     chat.muted       = true;
-    chat.muteUntilMs = muteEnd > 0 ? (muteEnd * 1000) : -1;
-    this.emit('chat_muted', { jid: jidFull, muted: true, until: chat.muteUntilMs });
-    return this._sendIq(node);
+    chat.muteUntilMs = endMs || -1;
+    this.emit('chat_muted', { jid: jidFull, muted: true, until: chat.muteUntilMs, synced });
+    return synced;
   }
 
-  // Unmute a chat — sends IQ to server (xmlns: 'w:web', add: '0')
   async unmuteChat(jid) {
     const jidFull = makeJid(jid);
-    const id = this._genMsgId();
-    const node = new BinaryNode('iq', {
-      id,
+    const synced  = await this._appStatePatchOrFallback(
+      AppMutations.mutePatch(jidFull, 0),
+      () => this._muteIq(jidFull, null));
+    const chat = this._getChatState(jidFull);
+    chat.muted       = false;
+    chat.muteUntilMs = 0;
+    this.emit('chat_muted', { jid: jidFull, muted: false, synced });
+    return synced;
+  }
+
+  // The mute a primary sends for itself. A companion never uses this — its
+  // mutes travel as app state so the phone learns about them.
+  _muteIq(jidFull, untilSeconds) {
+    const attrs = { jid: jidFull, add: untilSeconds === null ? '0' : '1' };
+    if (untilSeconds) attrs.t = String(untilSeconds);
+    return this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
       to:    's.whatsapp.net',
       type:  'set',
       xmlns: 'w:web'
-    }, [new BinaryNode('mute', { jid: jidFull, add: '0' }, null)]);
-    const chat = this._getChatState(jid);
-    chat.muted       = false;
-    chat.muteUntilMs = 0;
-    this.emit('chat_muted', { jid: jidFull, muted: false });
-    return this._sendIq(node);
+    }, [new BinaryNode('mute', attrs, null)]));
   }
 
   // Block a contact. Returns the updated block list.
@@ -4516,45 +5039,68 @@ class WhalibmobClient extends EventEmitter {
     return this._parseBlocklist(findChild(resp, 'list')).jids;
   }
 
-  // Pin / unpin a chat (mobile: local state)
-  pinChat(jid) {
-    const chat = this._getChatState(jid);
-    chat.pinnedAt = Math.floor(Date.now() / 1000);
-    this.emit('chat_pinned', { jid, pinned: true });
+  // ─── Chat state ───────────────────────────────────────────────────────────
+  //
+  // Pinning, archiving, muting, marking read and starring are not local
+  // preferences — they are app state, which is how a change reaches the phone
+  // and every other linked device. Each of these writes a patch and waits for
+  // the server to take it; the local view only moves once it has.
+  //
+  // These used to set a field on an in-memory object and emit an event, so a
+  // pin lasted until the process exited and never appeared anywhere else.
+
+  async pinChat(jid) {
+    const jidFull = makeJid(jid);
+    const synced  = await this._appStatePatchOrFallback(AppMutations.pinPatch(jidFull, true));
+    this._getChatState(jidFull).pinnedAt = Math.floor(Date.now() / 1000);
+    this.emit('chat_pinned', { jid: jidFull, pinned: true, synced });
+    return synced;
+  }
+
+  async unpinChat(jid) {
+    const jidFull = makeJid(jid);
+    const synced  = await this._appStatePatchOrFallback(AppMutations.pinPatch(jidFull, false));
+    this._getChatState(jidFull).pinnedAt = 0;
+    this.emit('chat_pinned', { jid: jidFull, pinned: false, synced });
+    return synced;
   }
 
-  unpinChat(jid) {
-    const chat = this._getChatState(jid);
-    chat.pinnedAt = 0;
-    this.emit('chat_pinned', { jid, pinned: false });
+  async archiveChat(jid) {
+    const jidFull = makeJid(jid);
+    const synced  = await this._appStatePatchOrFallback(AppMutations.archivePatch(jidFull, true));
+    this._getChatState(jidFull).archived = true;
+    this.emit('chat_archived', { jid: jidFull, archived: true, synced });
+    return synced;
   }
 
-  // Archive / unarchive a chat (mobile: local state)
-  archiveChat(jid) {
-    const chat = this._getChatState(jid);
-    chat.archived = true;
-    this.emit('chat_archived', { jid, archived: true });
+  async unarchiveChat(jid) {
+    const jidFull = makeJid(jid);
+    const synced  = await this._appStatePatchOrFallback(AppMutations.archivePatch(jidFull, false));
+    this._getChatState(jidFull).archived = false;
+    this.emit('chat_archived', { jid: jidFull, archived: false, synced });
+    return synced;
   }
 
-  unarchiveChat(jid) {
-    const chat = this._getChatState(jid);
-    chat.archived = false;
-    this.emit('chat_archived', { jid, archived: false });
+  // fromMe says whether the message being starred is one of ours. It is part of
+  // the index, so getting it wrong stars a different message — or nothing.
+  async starMessage(msgId, chatJid, fromMe) {
+    return this._setStar(msgId, chatJid, fromMe, true);
   }
 
-  // Star / unstar a message (mobile: local state)
-  starMessage(msgId, chatJid) {
-    const key = `${chatJid}:${msgId}`;
-    if (!this._starredMessages) this._starredMessages = new Set();
-    this._starredMessages.add(key);
-    this.emit('message_starred', { msgId, chatJid, starred: true });
+  async unstarMessage(msgId, chatJid, fromMe) {
+    return this._setStar(msgId, chatJid, fromMe, false);
   }
 
-  unstarMessage(msgId, chatJid) {
-    const key = `${chatJid}:${msgId}`;
+  async _setStar(msgId, chatJid, fromMe, starred) {
+    const jidFull = makeJid(chatJid);
+    const synced  = await this._appStatePatchOrFallback(
+      AppMutations.starPatch(jidFull, msgId, !!fromMe, starred));
     if (!this._starredMessages) this._starredMessages = new Set();
-    this._starredMessages.delete(key);
-    this.emit('message_starred', { msgId, chatJid, starred: false });
+    const key = jidFull + ':' + msgId;
+    if (starred) this._starredMessages.add(key); else this._starredMessages.delete(key);
+    this.emit('message_starred',
+      { msgId, chatJid: jidFull, starred, fromMe: !!fromMe, synced });
+    return synced;
   }
 
   // Mark a voice/audio message as played (sends 'played' receipt)
@@ -4673,17 +5219,19 @@ class WhalibmobClient extends EventEmitter {
   // opts: { ephemeralSeconds, announce, locked, joinApprovalRequired,
   //         memberAddMode, parent, linkedParentJid }
   //
-  // Built the way whatsmeow's CreateGroup does: every participant is a binary
-  // JID (a raw string is dropped for an @lid), a LID participant also carries
-  // the phone number the server matches it against, and each carries our privacy
-  // token so the invite is not treated as an anonymous reach-out. The setting
-  // nodes are siblings of the participants inside <create>.
+  // Every participant goes out as a binary JID (a raw string is dropped for an
+  // @lid), a LID participant also carries the phone number the server matches it
+  // against, and each carries our privacy token so the invitation is not treated
+  // as an anonymous reach-out. The setting nodes are siblings of the
+  // participants inside <create>.
   async createGroup(subject, participants, opts) {
     opts = opts || {};
     const id       = this._genMsgId();
     // participant nodes MUST use attr `jid`, not `value`
     const partNodes = (participants || []).map(p => {
-      const jid   = makeJid(p);
+      // A participant is the person, never one of their devices — a JID that
+      // still carries a device suffix is not one the server will match.
+      const jid   = toNonAdJid(makeJid(p));
       const attrs = { jid: jidStrToObj(jid) };
       if (jid.endsWith('@lid')) {
         const pn = this._lidToPn.get(jid.split('@')[0].split(':')[0]);
@@ -4708,7 +5256,7 @@ class WhalibmobClient extends EventEmitter {
     if (opts.locked)   settingNodes.push(new BinaryNode('locked', {}, null));
     if (opts.announce) settingNodes.push(new BinaryNode('announcement', {}, null));
     if (opts.ephemeralSeconds) {
-      // whatsmeow sends trigger="1" alongside the expiration; without it the
+      // trigger="1" has to travel alongside the expiration; without it the
       // server accepts the group but leaves disappearing messages off.
       settingNodes.push(new BinaryNode('ephemeral', {
         expiration: String(opts.ephemeralSeconds),
@@ -4725,7 +5273,11 @@ class WhalibmobClient extends EventEmitter {
         Buffer.from(String(opts.memberAddMode), 'utf8')));
     }
 
-    const baseAttrs = { subject, key: String(Math.floor(Date.now() / 1000)) };
+    // `key` is what the server echoes back on the group-create notification so
+    // the client can tell its own creation apart from one it merely witnessed.
+    // A per-second value collides when two groups are made in the same second;
+    // a message id does not.
+    const baseAttrs = { subject, key: this._genMsgId() };
     const createChildren = [...partNodes, ...settingNodes];
     const node = new BinaryNode('iq', {
       id,
@@ -4772,7 +5324,12 @@ class WhalibmobClient extends EventEmitter {
     return this._sendIq(node);
   }
 
-  // Add participants to group
+  // Add participants to group.
+  //
+  // Returns one result per participant, successes and failures alike — see
+  // _groupParticipantAction. A participant refused with 403 usually carries an
+  // `addRequest`, which sendGroupInvite() turns into an invitation they can act
+  // on themselves.
   async addGroupParticipants(groupJid, jids) {
     return this._groupParticipantAction(groupJid, 'add', jids);
   }
@@ -4797,10 +5354,10 @@ class WhalibmobClient extends EventEmitter {
   async _groupParticipantAction(groupJid, action, jids) {
     const gJid = makeJid(groupJid);
     const arr  = Array.isArray(jids) ? jids : [jids];
-    // Same shape whatsmeow's UpdateGroupParticipants builds: binary JIDs, and on
-    // an add, the phone number behind a LID plus our privacy token for them.
+    // Binary JIDs, and on an add, the phone number behind a LID plus our
+    // privacy token for them.
     const participantNodes = arr.map(j => {
-      const jid   = makeJid(j);
+      const jid   = toNonAdJid(makeJid(j));
       const attrs = { jid: jidStrToObj(jid) };
       let children = null;
       if (action === 'add') {
@@ -4823,36 +5380,48 @@ class WhalibmobClient extends EventEmitter {
       new BinaryNode(action, {}, participantNodes)
     ]);
     const resp = await this._sendIq(node);
-    if (!resp) return [];
+    if (!resp) throw new Error(action + ': no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      const text    = errNode && errNode.attrs && errNode.attrs.text;
+      throw new Error(action + ': server rejected the request' +
+        (code ? ' (' + code + (text ? ' ' + text : '') + ')' : ''));
+    }
     const actionNode = findChild(resp, action);
-    if (!actionNode || !Array.isArray(actionNode.content)) return [];
-    return actionNode.content
-      .filter(n => n && n.description === 'participant' && n.attrs && !n.attrs.error)
-      .map(n => n.attrs.jid || n.attrs.value)
-      .filter(Boolean);
+    if (!actionNode) {
+      throw new Error(action + ': server reply contained no <' + action + '> node');
+    }
+    // The membership changed, so anything we have cached about the group is now
+    // one edit behind.
+    this.invalidateGroupMetadata(gJid);
+    return parseParticipantNodes(actionNode);
   }
 
   // Change group name/subject
   async changeGroupSubject(groupJid, subject) {
-    const id = this._genMsgId();
+    const gJid = makeJid(groupJid);
+    const id   = this._genMsgId();
     const node = new BinaryNode('iq', {
       id,
       xmlns: 'w:g2',
-      to:    makeJid(groupJid),
+      to:    jidStrToObj(gJid),
       type:  'set'
     }, [
       new BinaryNode('subject', {}, Buffer.from(subject, 'utf8'))
     ]);
-    return this._sendIq(node);
+    const resp = await this._sendIq(node);
+    this.invalidateGroupMetadata(gJid);
+    return resp;
   }
 
   // Change group description
   // description: string or null/'' to remove
   //
-  // whatsmeow's SetGroupTopic sends prev=<current topic id> so the server can
-  // reject an edit made against a description someone else has already replaced.
-  // Without it the change is refused. The current id is looked up from the group
-  // metadata when the caller does not supply one.
+  // prev=<current topic id> has to go out with the edit so the server can reject
+  // one made against a description someone else has already replaced. Without it
+  // the change is refused. The current id is looked up from the group metadata
+  // when the caller does not supply one.
   async changeGroupDescription(groupJid, description, opts) {
     opts = opts || {};
     const gJid = makeJid(groupJid);
@@ -4883,13 +5452,14 @@ class WhalibmobClient extends EventEmitter {
     }, [
       new BinaryNode('description', descAttrs, children)
     ]);
-    return this._sendIq(node);
+    const resp = await this._sendIq(node);
+    this.invalidateGroupMetadata(gJid);
+    return resp;
   }
 
   // ─── Group settings ───────────────────────────────────────────────────────
   //
-  // Both are a single empty node whose TAG carries the state, exactly as
-  // whatsmeow's SetGroupAnnounce / SetGroupLocked send them — there is no
+  // Both are a single empty node whose TAG carries the state — there is no
   // attribute form of these.
 
   // announce=true → only admins can send messages
@@ -4941,27 +5511,42 @@ class WhalibmobClient extends EventEmitter {
     return resp;
   }
 
-  // Change group picture
-  // buf: Buffer with JPEG image data, or null to remove
+  // Change group picture.
+  //
+  // buf: Buffer with JPEG image data, or null to remove the current picture.
+  // Returns the new picture id, or 'remove' when the picture was taken down.
+  //
+  // Removal is the IQ with no body at all — an empty <picture> node is a
+  // malformed upload rather than a delete, and the server answers 406 for it.
   async changeGroupPicture(groupJid, buf) {
     const id = this._genMsgId();
     const node = new BinaryNode('iq', {
       id,
       xmlns:  'w:profile:picture',
-      target: makeJid(groupJid),
+      target: jidStrToObj(makeJid(groupJid)),
       to:     's.whatsapp.net',
       type:   'set'
-    }, [
-      new BinaryNode('picture', { type: 'image' }, buf || null)
-    ]);
-    return this._sendIq(node);
+    }, buf ? [new BinaryNode('picture', { type: 'image' }, buf)] : null);
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error('changeGroupPicture: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('changeGroupPicture: ' +
+        (String(code) === '406' ? 'the image was rejected (must be a JPEG)'
+       : String(code) === '403' ? 'you are not allowed to change this group picture'
+       : 'server rejected the request' + (code ? ' (' + code + ')' : '')));
+    }
+    if (!buf) return 'remove';
+    const picNode = findChild(resp, 'picture');
+    return (picNode && picNode.attrs && picNode.attrs.id)
+      ? String(picNode.attrs.id) : null;
   }
 
   // Get the group's invite link.
   //
   // reset=true revokes the current link and returns a freshly minted one — the
-  // same IQ with type="set" instead of "get", which is how whatsmeow's
-  // GetGroupInviteLink handles its reset flag.
+  // same IQ with type="set" instead of "get".
   async queryGroupInviteLink(groupJid, reset) {
     const code = await this._queryGroupInviteCode(groupJid, reset);
     return code ? INVITE_LINK_PREFIX + code : null;
@@ -4990,8 +5575,8 @@ class WhalibmobClient extends EventEmitter {
     if (resp.attrs && resp.attrs.type === 'error') {
       const errNode = findChild(resp, 'error');
       const codeAttr = errNode && errNode.attrs && errNode.attrs.code;
-      // whatsmeow maps these two specifically: 410 is a revoked link, 406 an
-      // invalid one. Anything else is passed through as the server worded it.
+      // 410 is a revoked link, 406 an invalid one. Anything else is passed
+      // through as the server worded it.
       const reason = String(codeAttr) === '410' ? 'the invite link has been revoked'
                    : String(codeAttr) === '406' ? 'the invite link is not valid'
                    : 'server rejected the request' +
@@ -5099,13 +5684,16 @@ class WhalibmobClient extends EventEmitter {
     return this._groupSettingIq(groupJid, body.description, body.content);
   }
 
-  // Query participants pending approval
+  // Query participants pending approval.
+  //
+  // Each entry stringifies to the JID and also carries `requestedAt`, the unix
+  // second the person asked to join, so a list can be shown oldest-first.
   async queryGroupPendingParticipants(groupJid) {
     const id = this._genMsgId();
     const node = new BinaryNode('iq', {
       id,
       xmlns: 'w:g2',
-      to:    makeJid(groupJid),
+      to:    jidStrToObj(makeJid(groupJid)),
       type:  'get'
     }, [
       new BinaryNode('membership_approval_requests', {}, null)
@@ -5116,22 +5704,26 @@ class WhalibmobClient extends EventEmitter {
     if (!reqNode || !Array.isArray(reqNode.content)) return [];
     return reqNode.content
       .filter(n => n && n.description === 'membership_approval_request')
-      .map(n => n.attrs && (n.attrs.user || n.attrs.jid))
+      .map(parseJoinRequestNode)
       .filter(Boolean);
   }
 
-  // Approve or reject pending join requests
+  // Approve or reject pending join requests.
+  //
+  // Returns one result per participant, refusals included, on the same terms as
+  // the add/remove/promote/demote actions.
   async approveGroupParticipants(groupJid, approve, jids) {
+    const gJid    = makeJid(groupJid);
     const arr     = Array.isArray(jids) ? jids : [jids];
     const action  = approve ? 'approve' : 'reject';
     const partNodes = arr.map(j =>
-      new BinaryNode('participant', { jid: makeJid(j) }, null)
+      new BinaryNode('participant', { jid: jidStrToObj(toNonAdJid(makeJid(j))) }, null)
     );
     const id = this._genMsgId();
     const node = new BinaryNode('iq', {
       id,
       xmlns: 'w:g2',
-      to:    makeJid(groupJid),
+      to:    jidStrToObj(gJid),
       type:  'set'
     }, [
       new BinaryNode('membership_requests_action', {}, [
@@ -5139,13 +5731,169 @@ class WhalibmobClient extends EventEmitter {
       ])
     ]);
     const resp = await this._sendIq(node);
-    if (!resp) return [];
+    if (!resp) throw new Error(action + ': no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const code    = errNode && errNode.attrs && errNode.attrs.code;
+      const text    = errNode && errNode.attrs && errNode.attrs.text;
+      throw new Error(action + ': server rejected the request' +
+        (code ? ' (' + code + (text ? ' ' + text : '') + ')' : ''));
+    }
     const actionNode = findChildDeep(resp, action);
-    if (!actionNode || !Array.isArray(actionNode.content)) return [];
-    return actionNode.content
-      .filter(n => n && n.description === 'participant' && !n.attrs.error)
-      .map(n => n.attrs && (n.attrs.value || n.attrs.jid))
-      .filter(Boolean);
+    if (!actionNode) {
+      throw new Error(action + ': server reply contained no <' + action + '> node');
+    }
+    this.invalidateGroupMetadata(gJid);
+    return parseParticipantNodes(actionNode);
+  }
+
+  // ─── Personal group invitations ───────────────────────────────────────────
+  //
+  // A group invite link is public: anyone holding it can join. These three are
+  // the other kind — an invitation minted for one named person, which is the
+  // only way into a group for someone whose privacy settings stop them from
+  // being added outright. The code comes back attached to the refusal from
+  // addGroupParticipants (`result.addRequest`), travels to them as a message
+  // built by sendGroupInvite, and is spent by acceptGroupInviteMessage.
+
+  // Send someone a personal invitation to a group.
+  //
+  // opts: { groupName, caption, jpegThumbnail, isCommunity, id, contextInfo }
+  //
+  // The group name is filled in from the group's own metadata when the caller
+  // does not supply one, so the bubble does not arrive nameless.
+  async sendGroupInvite(to, groupJid, inviteCode, inviteExpiration, opts) {
+    if (!this._sender || !this._connected) throw new Error('Not connected');
+    opts = opts || {};
+    const gJid = makeJid(groupJid);
+    let groupName = opts.groupName;
+    if (groupName === undefined) {
+      try {
+        const meta = await this.getGroupMetadata(gJid);
+        groupName = (meta && meta.subject) || '';
+      } catch (_) { groupName = ''; }
+    }
+    return this._sender.sendGroupInvite(to, gJid, inviteCode, inviteExpiration,
+      Object.assign({}, opts, { groupName }));
+  }
+
+  // Look at a group behind a personal invitation without accepting it.
+  //
+  // inviterJid is who sent the invitation; code and expiration come from the
+  // invite message itself.
+  async queryGroupInviteMessageInfo(groupJid, inviterJid, code, expiration) {
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      xmlns: 'w:g2',
+      to:    jidStrToObj(makeJid(groupJid)),
+      type:  'get'
+    }, [
+      new BinaryNode('query', {}, [
+        new BinaryNode('add_request', {
+          code:       String(code),
+          expiration: String(expiration || 0),
+          admin:      jidStrToObj(makeJid(inviterJid))
+        }, null)
+      ])
+    ]);
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error('queryGroupInviteMessageInfo: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const errCode = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('queryGroupInviteMessageInfo: ' +
+        (String(errCode) === '410' ? 'the invitation has expired'
+       : String(errCode) === '406' ? 'the invitation is not valid'
+       : 'server rejected the request' + (errCode ? ' (' + errCode + ')' : '')));
+    }
+    const grp = findChild(resp, 'group');
+    if (!grp) throw new Error('queryGroupInviteMessageInfo: server reply contained no <group> node');
+    return this._parseGroupNode(grp);
+  }
+
+  // Accept a personal invitation. Returns the JID of the group joined.
+  async acceptGroupInviteMessage(groupJid, inviterJid, code, expiration) {
+    const gJid = makeJid(groupJid);
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      xmlns: 'w:g2',
+      to:    jidStrToObj(gJid),
+      type:  'set'
+    }, [
+      new BinaryNode('accept', {
+        code:       String(code),
+        expiration: String(expiration || 0),
+        admin:      jidStrToObj(makeJid(inviterJid))
+      }, null)
+    ]);
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error('acceptGroupInviteMessage: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const errCode = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('acceptGroupInviteMessage: ' +
+        (String(errCode) === '410' ? 'the invitation has expired'
+       : String(errCode) === '406' ? 'the invitation is not valid'
+       : 'server rejected the request' + (errCode ? ' (' + errCode + ')' : '')));
+    }
+    this.invalidateGroupMetadata(gJid);
+    return (resp.attrs && resp.attrs.from) ? String(resp.attrs.from) : gJid;
+  }
+
+  // Withdraw a personal invitation you sent, before it is used.
+  async revokeGroupInviteForParticipant(groupJid, invitedJid) {
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      xmlns: 'w:g2',
+      to:    jidStrToObj(makeJid(groupJid)),
+      type:  'set'
+    }, [
+      new BinaryNode('revoke', {}, [
+        new BinaryNode('participant', { jid: jidStrToObj(toNonAdJid(makeJid(invitedJid))) }, null)
+      ])
+    ]);
+    const resp = await this._sendIq(node);
+    if (!resp) throw new Error('revokeGroupInviteForParticipant: no reply from server (IQ timed out)');
+    if (resp.attrs && resp.attrs.type === 'error') {
+      const errNode = findChild(resp, 'error');
+      const errCode = errNode && errNode.attrs && errNode.attrs.code;
+      throw new Error('revokeGroupInviteForParticipant: server rejected the request' +
+        (errCode ? ' (' + errCode + ')' : ''));
+    }
+    return true;
+  }
+
+  // Add participants, and for every one the server refuses because they cannot
+  // be added directly, send them a personal invitation instead.
+  //
+  // Returns the same list addGroupParticipants returns, with `invited` set on
+  // the entries an invitation went out to.
+  async addGroupParticipantsOrInvite(groupJid, jids, opts) {
+    opts = opts || {};
+    const gJid    = makeJid(groupJid);
+    const results = await this.addGroupParticipants(gJid, jids);
+    const pending = results.filter(r => r.needsInvite);
+    if (!pending.length) return results;
+
+    let groupName = opts.groupName;
+    if (groupName === undefined) {
+      try {
+        const meta = await this.getGroupMetadata(gJid);
+        groupName = (meta && meta.subject) || '';
+      } catch (_) { groupName = ''; }
+    }
+
+    for (const r of pending) {
+      try {
+        await this.sendGroupInvite(r.jid, gJid, r.addRequest.code,
+          r.addRequest.expiration, Object.assign({}, opts, { groupName }));
+        r.invited = true;
+      } catch (err) {
+        r.invited = false;
+        r.inviteError = err.message || String(err);
+      }
+    }
+    return results;
   }
 }