whalibmob 5.14.19 → 5.16.0

package/index.js

@@ -7,6 +7,7 @@ const SessionPaths = require('./lib/SessionPaths');
 const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts, storeToJson, storeFromJson } = require('./lib/Store');
 const { checkIfRegistered, requestSmsCode, verifyCode } = require('./lib/Registration');
 const { SignalProtocol } = require('./lib/signal/SignalProtocol');
+const WAM = require('./lib/WAM');
 const { SignalStore } = require('./lib/signal/SignalStore');
 const { SenderKeyStore, SenderKeyCrypto } = require('./lib/signal/SenderKey');
 const { DeviceManager } = require('./lib/DeviceManager');
@@ -103,6 +104,14 @@ module.exports = {
   encodeCompanionRegisterPayload,
   encodeCompanionLoginPayload,
   fetchWaWebVersion,
+  // WAM — the web client's stats channel: the event/global tables, the binary
+  // encoder and the BinaryInfo holder, all as the reference client defines
+  // them. See client.wamBuffer / client.sendWAMBuffer().
+  WAM,
+  encodeWAM:  WAM.encodeWAM,
+  BinaryInfo: WAM.BinaryInfo,
+  WEB_EVENTS: WAM.WEB_EVENTS,
+  WEB_GLOBALS: WAM.WEB_GLOBALS,
   // Signal / encryption internals
   SignalProtocol,
   SignalStore,

package/lib/Client.js

@@ -175,6 +175,18 @@ const RECONNECT_BACKOFF   = [1000, 2000, 4000, 8000, 15000, 30000];
 
 // How many attempts an upload gets before it is left for the next check, and
 // how long it waits between them.
+// How long a placeholder resend waits before it is actually asked for, and how
+// long it waits for an answer before the request is forgotten. The first is
+// there because most of these resolve on their own; the second because a phone
+// that is switched off will never answer and the entry must not block a later
+// attempt forever.
+const PLACEHOLDER_SETTLE_MS  = 2000;
+const PLACEHOLDER_TIMEOUT_MS = 8000;
+// An hour, matching the reference client, and a ceiling so a flood of
+// undecryptable stanzas cannot grow the map without bound.
+const PLACEHOLDER_TTL_MS     = 60 * 60 * 1000;
+const PLACEHOLDER_MAX        = 500;
+
 const PRE_KEY_UPLOAD_TRIES   = 4;
 const PRE_KEY_UPLOAD_BACKOFF = (attempt) => Math.min(1000 * Math.pow(2, attempt), 10000);
 
@@ -381,6 +393,19 @@ class WhalibmobClient extends EventEmitter {
     // One mutex per client — two accounts in the same process are unrelated
     // and must not wait on each other.
     this._preKeyMutex             = new Mutex();
+    // How far this machine's clock is from the server's, in milliseconds.
+    //
+    // The server stamps `t` on the stanzas that matter — <success> and
+    // pair-success — and the unified_session id is derived from a clock that is
+    // supposed to be the server's, not ours. Computing it from Date.now() alone
+    // makes the id drift by however wrong the local clock is, which on a phone
+    // or a container without NTP can be minutes. Zero until the server says
+    // otherwise, which is the same as not correcting at all.
+    this._serverTimeOffsetMs      = 0;
+    // Message ids we have asked the phone to resend, and have not seen since.
+    // An entry is the request itself: while it is there, no second request for
+    // that id goes out. Bounded and time-limited — see _placeholderResendCache.
+    this.__placeholderResend      = new Map();
     // Incoming work runs one item at a time, in arrival order.
     //
     // Stanzas arrive faster than they are handled, and the handling is
@@ -926,6 +951,11 @@ class WhalibmobClient extends EventEmitter {
   async _handleCompanionFinish(node) {
     const { buildCompanionFinishBundle } = require('./PairingCode');
 
+    // Same as the reference client does on pair-success: this stanza carries
+    // the server's clock, and the unified_session sent a moment later is
+    // derived from it.
+    this._updateServerTimeOffset(node);
+
     const reg = findChild(node, 'link_code_companion_reg');
     if (!reg) return;
 
@@ -1084,11 +1114,27 @@ class WhalibmobClient extends EventEmitter {
   // pairing and after each login. It carries no state we need; sending it keeps
   // our traffic shaped like the client we are claiming to be. Failures are
   // ignored, as they are in the reference.
+  // Take the server's clock from whatever stanza carries it.
+  //
+  // Mirrors the reference client: read `t` off <success> and off pair-success,
+  // and keep the difference from ours. Anything unparseable or non-positive is
+  // ignored rather than allowed to poison the offset.
+  _updateServerTimeOffset(node) {
+    const t = node && node.attrs && node.attrs.t;
+    if (!t) return;
+    const parsed = Number(t);
+    if (!Number.isFinite(parsed) || parsed <= 0) return;
+    this._serverTimeOffsetMs = parsed * 1000 - Date.now();
+    _whaDbg('[DBG] SERVER_TIME_OFFSET ' + this._serverTimeOffsetMs + 'ms');
+  }
+
   _sendUnifiedSession() {
     if (this._mode !== 'web' || !this._socket) return;
     try {
       const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
-      const id = ((Date.now() + 3 * 24 * 60 * 60 * 1000) % WEEK_MS).toString();
+      // Server clock, not ours — see _serverTimeOffsetMs.
+      const now = Date.now() + this._serverTimeOffsetMs;
+      const id = ((now + 3 * 24 * 60 * 60 * 1000) % WEEK_MS).toString();
       this._socket.sendNode(new BinaryNode('ib', {}, [
         new BinaryNode('unified_session', { id }, null)
       ]));
@@ -1305,6 +1351,9 @@ class WhalibmobClient extends EventEmitter {
     // ── Feature 1: Parse <success> node ──────────────────────────────────────
     // Extract ADVSignedDeviceIdentity, platform, and other account info that
     // the server provides on each successful authentication.
+    // The server's clock, before anything derived from it is computed.
+    this._updateServerTimeOffset(successNode);
+
     this._parseSuccessNode(successNode);
 
     // ── Feature 3 (part A): Send <active> IQ ─────────────────────────────────
@@ -2044,6 +2093,27 @@ class WhalibmobClient extends EventEmitter {
 
   // ─── Node dispatch ────────────────────────────────────────────────────────
 
+  // The queue the reconnect backlog drains through. Built on first use so a
+  // session that never goes offline never pays for it.
+  get _offlineQueue() {
+    if (!this.__offlineQueue) {
+      const { makeOfflineNodeProcessor } = require('./OfflineNodeProcessor');
+      this.__offlineQueue = makeOfflineNodeProcessor(new Map([
+        ['message',      (n) => this._handleMessage(n)],
+        ['receipt',      (n) => this._handleReceipt(n)],
+        ['notification', (n) => this._handleNotification(n)],
+        ['call',         (n) => this._handleCall(n)]
+      ]), {
+        isOpen:  () => !!(this._socket && this._connected),
+        onError: (err, ctx) => {
+          _whaDbg('[DBG] OFFLINE_QUEUE_ERR ' + ctx + ': ' + (err && err.message));
+          this.emit('node_error', { tag: ctx, err });
+        }
+      });
+    }
+    return this.__offlineQueue;
+  }
+
   _onNode(node) {
     if (!node || !node.description) return;
     const tag = node.description;
@@ -2061,6 +2131,16 @@ class WhalibmobClient extends EventEmitter {
     // behind it in the same offline batch was lost. Contain it: log the stanza
     // that did it, tell the caller, carry on reading.
     try {
+      // Backlog from the reconnect, not live traffic. The server stamps these
+      // `offline`, and handling a burst of them the way live stanzas are
+      // handled starts every one of them at once — see OfflineNodeProcessor.
+      if (node.attrs && node.attrs.offline &&
+          (tag === 'message' || tag === 'receipt' ||
+           tag === 'notification' || tag === 'call')) {
+        this._offlineQueue.enqueue(tag, node);
+        return;
+      }
+
       if      (tag === 'iq')           this._handleIq(node);
       else if (tag === 'message')      this._handleMessage(node);
       else if (tag === 'receipt')      this._handleReceipt(node);
@@ -2517,6 +2597,9 @@ class WhalibmobClient extends EventEmitter {
           return;
         }
 
+        // If we had asked the phone to resend this one, it has answered.
+        this._resolvePlaceholderResend(id);
+
         this.emit('message', { id, from, participant, ts, decoded, node });
         this._sendReadReceipt(id, fromRaw, partRaw);
 
@@ -3053,6 +3136,29 @@ class WhalibmobClient extends EventEmitter {
 
     if (!this._socket || !this._connected) return;
 
+    // Ask the phone as well, for the first couple of rounds.
+    //
+    // The retry receipt asks the *sender* to encrypt it again, which only helps
+    // when their session is the thing that went wrong. When ours is — a spent
+    // pre-key, a ratchet that moved on — no amount of asking them helps, and
+    // the plaintext is sitting on our own phone the whole time. The reference
+    // client asks both, and gives up on the phone after two rounds.
+    //
+    // Deliberately not awaited: a retry receipt must go out now, and this is a
+    // slower second route to the same message.
+    if (count <= 2) {
+      const attrs = (origNode && origNode.attrs) || {};
+      const from  = attrs.from ? String(attrs.from) : null;
+      if (from) {
+        this.requestPlaceholderResend({
+          remoteJid: from,
+          fromMe:    false,
+          id:        msgId
+        }).catch(err =>
+          _whaDbg('[DBG] PLACEHOLDER request failed: ' + (err && err.message)));
+      }
+    }
+
     // Pick a prekey that is not already advertised by another unresolved retry.
     // A prekey is deleted the moment a pkmsg using it is decrypted, so handing
     // the same one to two senders means the second arrives after the key is
@@ -3839,6 +3945,213 @@ class WhalibmobClient extends EventEmitter {
     this._ensureServerPreKeys('server asked');
   }
 
+  // Outstanding resend requests, with an hour's memory and a ceiling.
+  //
+  // A plain Map would hold every id the session ever failed to decrypt. The TTL
+  // is what the reference client uses; the ceiling is what keeps a burst of
+  // undecryptable stanzas from growing it without bound, dropping the oldest
+  // entries first — the ones whose request has already timed out anyway.
+  get _placeholderResendCache() {
+    const map = this.__placeholderResend;
+    const now = Date.now();
+    return {
+      has: (id) => {
+        const e = map.get(id);
+        if (!e) return false;
+        if (Date.now() - e.at > PLACEHOLDER_TTL_MS) { map.delete(id); return false; }
+        return true;
+      },
+      get: (id) => {
+        const e = map.get(id);
+        if (!e) return undefined;
+        if (Date.now() - e.at > PLACEHOLDER_TTL_MS) { map.delete(id); return undefined; }
+        return e.value;
+      },
+      set: (id, value) => {
+        map.set(id, { value, at: now });
+        // Map keeps insertion order, so the first key is the oldest.
+        while (map.size > PLACEHOLDER_MAX) map.delete(map.keys().next().value);
+      },
+      delete: (id) => map.delete(id),
+      get size() { return map.size; }
+    };
+  }
+
+  // ─── Peer data operations, and asking the phone to resend ─────────────────
+  //
+  // A peer-data-operation request is how a companion asks its own phone for
+  // something. It goes out as a ProtocolMessage addressed to this account, with
+  // the stanza marked category="peer" so the server routes it to the other
+  // devices instead of delivering it as a chat message to yourself.
+  //
+  // @param {object} pdo  see encodePeerDataOperationRequestMessage
+  // @returns {Promise<string>} the id of the message that carried the request
+  async sendPeerDataOperationMessage(pdo) {
+    if (!this._sender || !this._connected) throw new Error('Not connected');
+    const me = this._store && this._store.me && this._store.me.id;
+    if (!me) throw new Error('Not authenticated');
+
+    const {
+      encodeMessage, encodeProtocolMessage,
+      encodePeerDataOperationRequestMessage,
+      PROTOCOL_TYPE_PEER_DATA_OPERATION_REQUEST
+    } = require('./proto/MessageProto');
+
+    const payload = encodeProtocolMessage({
+      type: PROTOCOL_TYPE_PEER_DATA_OPERATION_REQUEST,
+      peerDataOperationRequestMessage: encodePeerDataOperationRequestMessage(pdo)
+    });
+    const msgBuf = encodeMessage('protocol', payload);
+    const msgId  = this._genMsgId();
+
+    await this._sender._sendMessage(String(me), msgId, msgBuf, 'text', {
+      _protocol:      true,           // not a reach-out; keeps it off the tcToken gate
+      category:       'peer',
+      pushPriority:   'high_force',
+      additionalNodes: [new BinaryNode('meta', { appdata: 'default' }, null)]
+    });
+    return msgId;
+  }
+
+  /**
+   * Ask the phone to send a message again.
+   *
+   * A message that cannot be decrypted — a session that moved on, a key that
+   * was already spent — is gone as far as this device is concerned. The phone
+   * still has the plaintext, so the fix is to ask it, not to retry the
+   * ciphertext.
+   *
+   * The cache is what stops that turning into a storm. One request per message
+   * id, and the entry is what says a request is outstanding:
+   *
+   *   • already asked            → say nothing, return
+   *   • it arrives within 2s     → the entry is gone, answer 'RESOLVED'
+   *   • no answer after 8s       → drop the entry so a later attempt may ask
+   *
+   * @param {{remoteJid: string, fromMe: boolean, id: string}} messageKey
+   * @param {object} [msgData]  metadata to keep for whatever handles the reply
+   * @returns {Promise<string|undefined|'RESOLVED'>}
+   */
+  async requestPlaceholderResend(messageKey, msgData) {
+    if (!messageKey || !messageKey.id) return;
+    const me = this._store && this._store.me && this._store.me.id;
+    if (!me) throw new Error('Not authenticated');
+
+    const cache = this._placeholderResendCache;
+    if (cache.has(messageKey.id)) {
+      _whaDbg('[DBG] PLACEHOLDER already requested for ' + messageKey.id);
+      return;
+    }
+    cache.set(messageKey.id, msgData || true);
+
+    // Give it a moment. Most of these resolve on their own — the message that
+    // failed to decrypt is very often followed by the sender's own retry.
+    await new Promise(r => setTimeout(r, PLACEHOLDER_SETTLE_MS));
+    if (!cache.has(messageKey.id)) {
+      _whaDbg('[DBG] PLACEHOLDER ' + messageKey.id + ' arrived before asking');
+      return 'RESOLVED';
+    }
+
+    // The phone may simply be off. Let the entry go so this is not the last
+    // word on the subject.
+    setTimeout(() => {
+      if (cache.has(messageKey.id)) {
+        _whaDbg('[DBG] PLACEHOLDER no answer for ' + messageKey.id + ' — phone likely offline');
+        cache.delete(messageKey.id);
+      }
+    }, PLACEHOLDER_TIMEOUT_MS).unref?.();
+
+    const { PeerDataOperationRequestType } = require('./proto/MessageProto');
+    _whaDbg('[DBG] PLACEHOLDER requesting resend of ' + messageKey.id);
+    return this.sendPeerDataOperationMessage({
+      peerDataOperationRequestType: PeerDataOperationRequestType.PLACEHOLDER_MESSAGE_RESEND,
+      placeholderMessageResendRequest: [{ messageKey }]
+    });
+  }
+
+  /**
+   * Ask the phone for older messages in a chat.
+   *
+   * The same channel, a different operation — this is what an on-demand
+   * history sync is built on.
+   */
+  async fetchMessageHistory(count, oldestMsgKey, oldestMsgTimestampMs) {
+    const { PeerDataOperationRequestType } = require('./proto/MessageProto');
+    return this.sendPeerDataOperationMessage({
+      peerDataOperationRequestType: PeerDataOperationRequestType.HISTORY_SYNC_ON_DEMAND,
+      historySyncOnDemandRequest: {
+        chatJid:              oldestMsgKey.remoteJid,
+        oldestMsgId:          oldestMsgKey.id,
+        oldestMsgFromMe:      !!oldestMsgKey.fromMe,
+        onDemandMsgCount:     count,
+        oldestMsgTimestampMs: oldestMsgTimestampMs
+      }
+    });
+  }
+
+  /** Note that a message we asked about has turned up, so nothing is owed. */
+  _resolvePlaceholderResend(msgId) {
+    if (msgId && this._placeholderResendCache.has(msgId)) {
+      this._placeholderResendCache.delete(msgId);
+      _whaDbg('[DBG] PLACEHOLDER resolved ' + msgId);
+    }
+  }
+
+  // ─── WAM — the stats channel WhatsApp Web reports on ──────────────────────
+  //
+  // A WAM buffer is a batch of telemetry events encoded in WhatsApp's own
+  // binary format and posted to `w:stats`. The web client sends these
+  // constantly; a companion session that never does is one more thing that
+  // distinguishes it from a browser.
+  //
+  // Nothing here fires on its own, and that matches the reference client's
+  // library exactly — it builds the same three pieces, exposes the same
+  // `wamBuffer` and the same `sendWAMBuffer`, and never calls the latter
+  // itself. What to report, and when, is the application's decision.
+  //
+  //   const { WAM } = require('whalibmob')
+  //
+  //   client.wamBuffer.sequence = 1
+  //   client.wamBuffer.events = [{
+  //     WamDroppedEvent: {
+  //       props:   { droppedEventCode: 3, droppedEventCount: 1, isFromWamsys: true },
+  //       globals: {}
+  //     }
+  //   }]
+  //   await client.sendWAMBuffer(WAM.encodeWAM(client.wamBuffer))
+  //
+  // The event and field names come from WAM.WEB_EVENTS and WAM.WEB_GLOBALS,
+  // which are the reference client's tables verbatim.
+
+  /** The buffer an application fills in before encoding. */
+  get wamBuffer() {
+    if (!this._wamBuffer) {
+      const { BinaryInfo } = require('./WAM');
+      this._wamBuffer = new BinaryInfo();
+    }
+    return this._wamBuffer;
+  }
+
+  /**
+   * Post an encoded WAM buffer to the server.
+   *
+   * @param   {Buffer} wamBuffer  output of WAM.encodeWAM()
+   * @returns {Promise<object|null>}  the server's IQ result, or null on timeout
+   */
+  async sendWAMBuffer(wamBuffer) {
+    if (!this._socket || !this._connected) throw new Error('Not connected');
+    if (!Buffer.isBuffer(wamBuffer)) {
+      throw new Error('sendWAMBuffer expects a Buffer from WAM.encodeWAM()');
+    }
+    return this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      xmlns: 'w:stats'
+    }, [
+      new BinaryNode('add', { t: String(Math.round(Date.now() / 1000)) }, wamBuffer)
+    ]));
+  }
+
   // ─── IQ helper (send + await response) ────────────────────────────────────
 
   _sendIq(node) {

package/lib/HistorySyncHandler.js

@@ -52,9 +52,17 @@ const HistorySyncType = {
   RECENT:            3,
   PUSH_NAME:         4,
   NON_BLOCKING_DATA: 5,
-  ON_DEMAND:         6
+  ON_DEMAND:         6,
+  // The server says these two outright rather than sending a payload, so a
+  // chunk of either kind has nothing to download and is not an error.
+  NO_HISTORY:            7,
+  MESSAGE_ACCESS_STATUS: 8
 };
 
+// Sync types that never carry a blob. Asking for one is the server telling us
+// there is nothing to fetch, not a chunk we failed to read.
+const PAYLOADLESS_SYNC_TYPES = new Set([7, 8]);
+
 const HistorySyncTypeName = Object.fromEntries(
   Object.entries(HistorySyncType).map(([k, v]) => [v, k])
 );
@@ -151,7 +159,24 @@ function decodeHistorySyncNotification(buf) {
       chunkOrder:                        typeof f[7] === 'number' ? f[7] : 0,
       originalMessageId:                 _str(f[8]),
       progress:                          typeof f[9] === 'number' ? f[9] : 0,
-      initialHistBootstrapInlinePayload: f[10] || null
+      oldestMsgInChunkTimestampSec:      _uint64(f[10]),
+      // Field 11, not 10.
+      //
+      // Ten is oldestMsgInChunkTimestampSec — a varint — so reading the inline
+      // payload from it never produced a Buffer, and the check that guards the
+      // inline path (`payload && payload.length > 0`) was therefore never true.
+      // Every chunk fell through to the download branch instead.
+      //
+      // That is fatal for exactly the chunk that matters. WhatsApp sends the
+      // initial bootstrap — the one carrying the conversations, and with them
+      // every contact's trusted-contact token — with its payload inline and no
+      // directPath at all. The download branch has nothing to download, throws
+      // 'missing directPath or mediaKey', and the whole history is lost. What
+      // survived was the chunks that do have a directPath, which are the ones
+      // with no conversations in them.
+      initialHistBootstrapInlinePayload: Buffer.isBuffer(f[11]) ? f[11] : null,
+      peerDataRequestSessionId:          _str(f[12]),
+      encHandle:                         _str(f[14])
     };
   } catch (e) {
     return null;
@@ -359,8 +384,12 @@ function decodeHistorySync(buf) {
   try {
     const f = _decodeFields(buf);
 
-    const syncType = typeof f[1] === 'number' ? f[1] : 0;
-    const progress = typeof f[5] === 'number' ? f[5] : 0;
+    // Five is chunkOrder and six is progress — this read five as the progress
+    // and never looked at six, so every chunk reported its ordinal as a
+    // percentage.
+    const syncType   = typeof f[1] === 'number' ? f[1] : 0;
+    const chunkOrder = typeof f[5] === 'number' ? f[5] : 0;
+    const progress   = typeof f[6] === 'number' ? f[6] : 0;
 
     const conversations = [];
     if (f[2]) {
@@ -373,9 +402,12 @@ function decodeHistorySync(buf) {
       }
     }
 
+    // Pushnames are field 7. Four is not a field of HistorySync at all, so this
+    // read undefined every time and a PUSH_NAME sync — whose entire content is
+    // this list — always arrived empty.
     const pushnames = [];
-    if (f[4]) {
-      const pnBufs = Array.isArray(f[4]) ? f[4] : [f[4]];
+    if (f[7]) {
+      const pnBufs = Array.isArray(f[7]) ? f[7] : [f[7]];
       for (const pb of pnBufs) {
         if (Buffer.isBuffer(pb)) {
           const p = decodePushName(pb);
@@ -384,9 +416,13 @@ function decodeHistorySync(buf) {
       }
     }
 
+    // phoneNumberToLidMappings is field 15. Ten is threadDsTimeframeOffset, a
+    // uint32, so the loop below was handed a number, found it was not a Buffer
+    // and skipped it — the mappings history carries were never read, and every
+    // LID had to be learnt again from live traffic.
     const lidPnMappings = [];
-    if (f[10]) {
-      const mapBufs = Array.isArray(f[10]) ? f[10] : [f[10]];
+    if (f[15]) {
+      const mapBufs = Array.isArray(f[15]) ? f[15] : [f[15]];
       for (const mb of mapBufs) {
         if (Buffer.isBuffer(mb)) {
           const m = decodeLidPnMapping(mb);
@@ -395,7 +431,7 @@ function decodeHistorySync(buf) {
       }
     }
 
-    return { syncType, progress, conversations, pushnames, lidPnMappings };
+    return { syncType, progress, chunkOrder, conversations, pushnames, lidPnMappings };
   } catch (e) {
     return null;
   }
@@ -679,9 +715,21 @@ async function processHistorySyncNotification(notification, sessionDir, phone) {
       notification.initialHistBootstrapInlinePayload.length > 0) {
     // Inline payload — no network call needed (zlib-compressed HistorySync proto)
     decompressed = await inflateBuffer(notification.initialHistBootstrapInlinePayload);
+  } else if (PAYLOADLESS_SYNC_TYPES.has(notification.syncType)) {
+    // NO_HISTORY and MESSAGE_ACCESS_STATUS are statements, not chunks. There is
+    // nothing to fetch and nothing went wrong, so answer with an empty result
+    // rather than raising an error the caller can only log.
+    return {
+      syncType: notification.syncType,
+      syncTypeName: typeName,
+      progress: notification.progress || 0,
+      chunkOrder: notification.chunkOrder || 0,
+      chats: [], contacts: [], pushNames: [], lidPnMappings: [], merged: null
+    };
   } else {
     if (!notification.directPath || !notification.mediaKey) {
-      throw new Error('HistorySyncNotification missing directPath or mediaKey');
+      throw new Error('HistorySyncNotification missing directPath or mediaKey' +
+        ' (syncType=' + typeName + ')');
     }
 
     const cdnUrl        = 'https://' + CDN_HOST + notification.directPath;

package/lib/OfflineNodeProcessor.js

@@ -0,0 +1,100 @@
+'use strict';
+
+// The backlog the server flushes on reconnect, processed at a pace that leaves
+// the process usable.
+//
+// Everything that arrived while this session was offline is delivered in one
+// burst the moment it reconnects — messages, receipts, notifications, calls,
+// stamped `offline` so a client can tell them from live traffic. On an account
+// that has been away for a day that burst is hundreds of stanzas.
+//
+// Handled the way live traffic is handled, they all start at once: hundreds of
+// decryptions, disk writes and event emissions racing each other with nothing
+// between them, and the event loop never gets a turn. Nothing else in the
+// process runs until the last one finishes — no timers, no keepalive, no socket
+// reads. And one handler that throws takes the rest of the burst with it.
+//
+// So the backlog gets a queue of its own:
+//
+//   • one stanza at a time, in the order the server sent them
+//   • the event loop gets a turn after every batch, so timers and the socket
+//     keep running while the backlog drains
+//   • a handler that throws is reported and the queue carries on — a single bad
+//     stanza costs one stanza, not the rest of the burst
+//   • a socket that closes mid-drain stops the queue rather than working
+//     through a backlog nobody can answer
+//
+// Live traffic does not come through here. It has no `offline` attribute and
+// goes straight to its handler, exactly as before.
+
+// How many stanzas to handle before giving the event loop a turn. The reference
+// client uses ten; more starves the loop, fewer spends the whole drain in
+// setImmediate round trips.
+const DEFAULT_BATCH_SIZE = 10;
+
+/**
+ * @param {Map<string, (node) => Promise<void>|void>} handlers  stanza tag → handler
+ * @param {object} deps
+ *   @param {() => boolean}        deps.isOpen     whether the socket is still up
+ *   @param {(err, ctx) => void}   deps.onError    called for anything a handler throws
+ *   @param {() => Promise<void>} [deps.yield]     how to give the loop a turn
+ * @param {number} [batchSize]
+ */
+function makeOfflineNodeProcessor(handlers, deps, batchSize) {
+  const size    = batchSize > 0 ? batchSize : DEFAULT_BATCH_SIZE;
+  const pending = [];
+  let draining  = false;
+
+  const yieldToLoop = (deps && deps.yield) ||
+    (() => new Promise(resolve => setImmediate(resolve)));
+
+  async function drain() {
+    let inBatch = 0;
+    while (pending.length && deps.isOpen()) {
+      const { tag, node } = pending.shift();
+      const handler = handlers.get(tag);
+
+      if (!handler) {
+        deps.onError(new Error('unknown offline stanza: ' + tag), 'offline ' + tag);
+        continue;
+      }
+
+      try {
+        await handler(node);
+      } catch (err) {
+        // Reported, not rethrown: the rest of the backlog is still worth having.
+        deps.onError(err, 'offline ' + tag);
+      }
+
+      if (++inBatch >= size) {
+        inBatch = 0;
+        await yieldToLoop();
+      }
+    }
+    draining = false;
+  }
+
+  return {
+    /** Put one stanza on the queue, and start draining if nothing else is. */
+    enqueue(tag, node) {
+      pending.push({ tag, node });
+      if (draining) return;
+      draining = true;
+      drain().catch(err => {
+        draining = false;
+        deps.onError(err, 'draining offline backlog');
+      });
+    },
+
+    /** How many stanzas are still waiting. */
+    get size() { return pending.length; },
+
+    /** Whether the queue is working through a backlog right now. */
+    get draining() { return draining; },
+
+    /** Throw the backlog away — used when the session is torn down. */
+    clear() { pending.length = 0; }
+  };
+}
+
+module.exports = { makeOfflineNodeProcessor, DEFAULT_BATCH_SIZE };

package/lib/WAM/BinaryInfo.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// What an outgoing WAM buffer is assembled from.
+//
+// Identical to Baileys' BinaryInfo: a protocol version, a sequence number that
+// the server uses to order buffers, the events queued for the next flush, and
+// the scratch list the encoder fills with byte chunks.
+
+class BinaryInfo {
+    constructor(options = {}) {
+        this.protocolVersion = 5;
+        this.sequence = 0;
+        this.events = [];
+        this.buffer = [];
+        Object.assign(this, options);
+    }
+}
+
+module.exports = { BinaryInfo };