whalibmob 5.5.39 → 5.5.40

package/README.md

@@ -130,6 +130,13 @@ npm install -g whalibmob
   - [Handling Events](#handling-events)
     - [Example to Start](#example-to-start)
     - [All Events](#all-events)
+  - [History Sync](#history-sync)
+    - [How It Works](#how-history-sync-works)
+    - [Listening to History Sync Events](#listening-to-history-sync-events)
+    - [Persistent Files Written to Disk](#persistent-files-written-to-disk)
+    - [Reading the History Store](#reading-the-history-store)
+    - [tcToken — Error 463 Defense](#tctoken--error-463-defense)
+    - [What Is Automatic vs What You Need to Do](#what-is-automatic-vs-what-you-need-to-do)
   - [Receiving Media](#receiving-media)
   - [Sending Messages](#sending-messages)
     - [Text Message](#text-message)
@@ -550,6 +557,261 @@ The `decoded` object shape per message type:
 { type: 'protocol', subtype: string }
 ```
 
+---
+
+## History Sync
+
+### How History Sync Works
+
+When whalibmob connects, WhatsApp automatically sends the account's chat history to the client.
+The library handles the entire pipeline **without any code from you** — you only need to listen
+to the events if you want to use the data.
+
+The full internal flow:
+
+1. WhatsApp server sends an encrypted `ProtocolMessage` (type 6) containing a `HistorySyncNotification`.
+2. The library decrypts it via Signal Protocol.
+3. `HistorySyncHandler` downloads the encrypted blob from WhatsApp's CDN (`mmg.whatsapp.net`), or reads the inline payload if the server embedded it directly.
+4. The blob is decrypted with **AES-256-CBC** using an HKDF key derived from `"WhatsApp History Keys"`.
+5. The result is decompressed with **zlib** and decoded from **protobuf** (WAProto v2.3000.x — field numbers verified against the official proto definition).
+6. Chats, contacts, push names, LID↔PN mappings, and **tcTokens** are merged into the disk store.
+7. tcTokens from history are seeded into `TcTokenStore` in memory so the first outbound DM after reconnect already carries a valid `<tctoken>` node (prevents error 463 on cold start).
+8. The `history_sync` event fires with a summary of what was received.
+
+History arrives in **multiple chunks**. Each chunk fires one `history_sync` event. The first chunk (sync type `INITIAL_BOOTSTRAP`) is usually the largest and carries the most recent conversations.
+
+### Listening to History Sync Events
+
+```js
+const { WhalibmobClient } = require('whalibmob')
+const path = require('path')
+
+const client = new WhalibmobClient({
+  sessionDir: path.join(process.env.HOME, '.waSession')
+})
+
+// history_sync fires once per history chunk — may fire multiple times on first connect
+client.on('history_sync', result => {
+  console.log('History sync chunk received:')
+  console.log('  type    :', result.syncTypeName)   // e.g. 'INITIAL_BOOTSTRAP', 'RECENT', 'FULL'
+  console.log('  progress:', result.progress)        // 0-100 server-reported
+  console.log('  chunk   :', result.chunkOrder)
+  console.log('  chats   :', result.chats.length)
+  console.log('  contacts:', result.contacts.length)
+  console.log('  pushNames:', (result.pushNames || []).length)
+})
+
+// history_sync_error fires if a chunk fails to download or decrypt
+client.on('history_sync_error', ({ err, notification }) => {
+  console.error('History sync failed:', err.message)
+  console.error('  syncType:', notification.syncType)
+})
+
+await client.init('919634847671')
+```
+
+The `result` object shape emitted by `history_sync`:
+
+```js
+{
+  syncType:      number,   // HistorySyncType enum value
+  syncTypeName:  string,   // 'INITIAL_BOOTSTRAP' | 'RECENT' | 'FULL' | 'PUSH_NAME' | 'NON_BLOCKING_DATA' | 'ON_DEMAND'
+  progress:      number,   // 0-100, server-reported progress
+  chunkOrder:    number,   // chunk sequence number
+  chats: [                 // one entry per conversation in this chunk
+    {
+      id:               string,   // chat JID e.g. '919634847671@s.whatsapp.net' or '120363...@g.us'
+      name:             string,   // display name (may be undefined for unknown contacts)
+      unreadCount:      number,
+      lastMsgTimestamp: number,   // Unix seconds
+      messageCount:     number    // number of messages in this chunk for this chat
+    }
+  ],
+  contacts: [              // one entry per contact discovered in this chunk
+    {
+      id:       string,
+      name:     string,
+      username: string,    // WhatsApp username if set
+      pnJid:    string,    // phone-number JID e.g. '919634847671@s.whatsapp.net'
+      lidJid:   string     // LID JID e.g. '112345678901234@lid'
+    }
+  ],
+  pushNames:     Array,    // push-name entries { id, pushname }
+  lidPnMappings: Array,    // LID<->PN mapping entries { lidJid, pnJid }
+  merged:        object    // raw merged history store (see Reading the History Store below)
+}
+```
+
+Sync type values:
+
+| `syncTypeName` | When it fires |
+|---|---|
+| `INITIAL_BOOTSTRAP` | First connect — most recent conversations |
+| `RECENT` | Reconnect after a short offline period |
+| `FULL` | Full historical sync (older messages) |
+| `PUSH_NAME` | Contact name updates only |
+| `NON_BLOCKING_DATA` | Background low-priority data |
+| `ON_DEMAND` | Explicitly requested by the client |
+
+### Persistent Files Written to Disk
+
+The library automatically writes these files to `sessionDir` per account. You do not need to create or manage them.
+
+| File | Contents |
+|---|---|
+| `<phone>.history.json` | Chats, contacts, push names, LID↔PN mappings, tcTokens |
+| `<phone>.messages.json` | Flat map of `msgId → message metadata` |
+| `<phone>.appStateKeys.json` | App-state sync keys (used for app-state patch decryption) |
+| `<phone>.tctoken.json` | Trusted-contact token store (tcToken per contact JID) |
+
+### Reading the History Store
+
+After history sync completes you can read the on-disk files directly:
+
+```js
+const fs   = require('fs')
+const path = require('path')
+
+const sessDir = path.join(process.env.HOME, '.waSession')
+const phone   = '919634847671'
+
+// ── Read chats ────────────────────────────────────────────────────────────────
+const histPath = path.join(sessDir, phone + '.history.json')
+const hist     = JSON.parse(fs.readFileSync(histPath, 'utf8'))
+
+// List all chats sorted by last message time
+const chats = Object.values(hist.chats)
+  .sort((a, b) => (b.lastMsgTimestamp || 0) - (a.lastMsgTimestamp || 0))
+
+for (const chat of chats.slice(0, 10)) {
+  console.log(chat.id, '|', chat.name || '(unknown)', '|', chat.unreadCount, 'unread')
+}
+
+// ── LID ↔ PN lookup ───────────────────────────────────────────────────────────
+// Look up LID JID from phone number JID
+const myLid = hist.pnLidMap['919634847671@s.whatsapp.net']
+console.log('LID:', myLid)   // e.g. '112345678901234@lid'
+
+// Reverse: phone number JID from LID
+const myPn = hist.lidPnMap[myLid]
+console.log('PN:', myPn)
+
+// ── Read message metadata ─────────────────────────────────────────────────────
+const msgPath = path.join(sessDir, phone + '.messages.json')
+const msgs    = JSON.parse(fs.readFileSync(msgPath, 'utf8'))
+const msgList = Object.values(msgs).sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
+console.log('Total messages indexed:', msgList.length)
+console.log('Latest:', msgList[0])
+```
+
+`hist.chats` schema per chat entry:
+
+```js
+{
+  id:                     string,   // JID
+  name:                   string,
+  displayName:            string,
+  unreadCount:            number,
+  lastMsgTimestamp:       number,   // Unix seconds
+  messageCount:           number,   // total messages indexed from history
+  ephemeralExpiry:        number,   // disappearing messages timer in seconds, if set
+  archived:               boolean,
+  pinned:                 number,   // pin sort order (0 = not pinned)
+  tcToken:                string,   // base64 — trusted-contact token (used internally by the library)
+  tcTokenTimestamp:       number,   // Unix seconds — when the token was issued by the server
+  tcTokenSenderTimestamp: number    // Unix seconds — sender-side issuance timestamp for 7-day bucket dedup
+}
+```
+
+`msgs` schema per message entry:
+
+```js
+{
+  id:        string,   // WhatsApp message ID
+  chatId:    string,   // JID of the conversation
+  fromMe:    boolean,
+  fromJid:   string,   // sender JID
+  timestamp: number,   // Unix seconds
+  pushName:  string,   // display name of sender at send time
+  status:    number    // 0=error 1=pending 2=server 3=delivered 4=read 5=played
+}
+```
+
+### tcToken — Error 463 Defense
+
+> [!IMPORTANT]
+> This section is informational. The entire tcToken lifecycle is **fully automatic**.
+> You do not need to write any code for it.
+
+WhatsApp counts every outbound DM sent **without** a `<tctoken>` node as an anonymous "reach-out" event. Once enough such events accumulate the server enforces a time-based **Reach-out Time-lock** and returns error `463` (`NackCallerReachoutTimelocked`), blocking all outbound messages and calls for a period.
+
+whalibmob implements the full lifecycle to prevent this:
+
+| Step | What the library does automatically |
+|---|---|
+| **History seed** | On every history sync chunk, `tcToken` bytes are extracted from each conversation in the protobuf and loaded into `TcTokenStore` in memory. The first send after reconnect already has a valid token ready — no 463 risk on cold start. |
+| **Attach on send** | Before dispatching any DM, `MessageSender` looks up the token for the recipient JID, checks it has not expired (28-day rolling window), and pushes a `<tctoken>` child node into the message stanza. |
+| **Proactive issuance** | After each successful DM send, the library fires a `<iq type='set' xmlns='privacy'>` requesting a fresh token for that JID from the server — once per 7-day bucket, deduplicated in-flight. |
+| **Incoming notification** | When a contact starts a new conversation, WhatsApp pushes a `<notification type='privacy_token'>`. The library catches it in `_handlePrivacyTokenNotification` and stores the token immediately. |
+| **Identity change re-issue** | When decrypting a `pkmsg` (new Signal session from peer), the library calls `_reissueTcTokenAfterIdentityChange` to re-issue the token for the new session. |
+| **Error 463 recovery** | If a send fails with error 463, the library issues a fresh token, waits for the server response, and automatically retries the same message with the new token attached. |
+| **Expiry** | Tokens use a 4-bucket rolling window (4 × 7 days = 28-day TTL). Expired tokens are cleared before the send and a fresh one is requested proactively. |
+
+Token storage uses the **LID JID** of the contact (e.g. `112345678901234@lid`) as the key — never the phone-number JID — matching WhatsApp's internal convention.
+
+### What Is Automatic vs What You Need to Do
+
+**Everything in the "Automatic" column requires zero code from you.**
+
+| Feature | Automatic | Notes |
+|---|---|---|
+| Download history blob from CDN | ✅ | |
+| Decrypt history blob (AES-256-CBC + HKDF) | ✅ | |
+| Decompress zlib | ✅ | |
+| Decode protobuf (WAProto v2.3000.x) | ✅ | Field numbers verified against official proto |
+| Persist chats / contacts / push names | ✅ | Written to `<phone>.history.json` |
+| Persist message metadata | ✅ | Written to `<phone>.messages.json` |
+| Persist app-state sync keys | ✅ | Written to `<phone>.appStateKeys.json` |
+| Seed tcTokens into memory on connect | ✅ | Prevents error 463 on first send after reconnect |
+| Attach tcToken to every outbound DM | ✅ | |
+| Issue fresh tcTokens after each send | ✅ | Once per 7-day bucket per contact |
+| Handle incoming `privacy_token` notifications | ✅ | |
+| Re-issue tcToken after peer identity change | ✅ | |
+| Recover from error 463 with automatic retry | ✅ | |
+| Populate in-memory LID↔PN maps | ✅ | |
+| Listen to `history_sync` event | 🔵 Optional | Only if your app needs to react to history data |
+| Read `<phone>.history.json` | 🔵 Optional | Only if your app needs chat/contact data at rest |
+| Read `<phone>.messages.json` | 🔵 Optional | Only if your app indexes messages |
+
+**Minimum working integration — history sync, tcTokens, and error-463 defense all active with zero extra code:**
+
+```js
+const { WhalibmobClient } = require('whalibmob')
+const path = require('path')
+
+const client = new WhalibmobClient({
+  sessionDir: path.join(process.env.HOME, '.waSession')
+})
+
+// History sync, tcToken seeding, error-463 defense, and all disk persistence
+// happen automatically. Add the listeners below only if your app needs the data.
+
+client.on('history_sync', result => {
+  // Optional — fires once per chunk (multiple times on first connect)
+  console.log('[', result.syncTypeName, ']',
+    result.chats.length, 'chats,',
+    result.contacts.length, 'contacts')
+})
+
+client.on('history_sync_error', ({ err }) => {
+  // Optional — log failures (library continues working even if a chunk fails)
+  console.error('History chunk failed:', err.message)
+})
+
+await client.init('919634847671')
+```
+
+
 ## Receiving Media
 
 When a media message arrives, `msg.decoded` contains a CDN `url` and a `mediaKey`.

package/index.js

@@ -17,6 +17,19 @@ const {
   assertMeId,
   initAuthCreds
 } = require('./lib/auth-utils');
+const {
+  processHistorySyncNotification,
+  decodeHistorySyncNotification,
+  decodeHistorySync,
+  decodeAppStateSyncKeyShare,
+  saveAppStateSyncKeys,
+  loadAppStateSyncKeys,
+  mergeHistoryToStore,
+  decryptHistoryBlob,
+  deriveHistoryKeys,
+  HistorySyncType,
+  HistorySyncTypeName
+} = require('./lib/HistorySyncHandler');
 
 module.exports = {
   WhalibmobClient,
@@ -59,5 +72,17 @@ module.exports = {
   makeCacheableSignalKeyStore,
   addTransactionCapability,
   assertMeId,
-  initAuthCreds
+  initAuthCreds,
+  // History sync
+  processHistorySyncNotification,
+  decodeHistorySyncNotification,
+  decodeHistorySync,
+  decodeAppStateSyncKeyShare,
+  saveAppStateSyncKeys,
+  loadAppStateSyncKeys,
+  mergeHistoryToStore,
+  decryptHistoryBlob,
+  deriveHistoryKeys,
+  HistorySyncType,
+  HistorySyncTypeName
 };

package/lib/Client.js

@@ -13,6 +13,13 @@ const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts } = requi
 const { BinaryNode }      = require('./BinaryNode');
 const { SignalProtocol }  = require('./signal/SignalProtocol');
 const { DeviceManager }   = require('./DeviceManager');
+const {
+  processHistorySyncNotification,
+  decodeHistorySyncNotification,
+  decodeAppStateSyncKeyShare,
+  saveAppStateSyncKeys,
+  HistorySyncType
+} = require('./HistorySyncHandler');
 
 const PING_INTERVAL_MS    = 25000;
 const KEEPALIVE_INTERVAL  = 20000;
@@ -699,8 +706,22 @@ class WhalibmobClient extends EventEmitter {
           return;
         }
 
-        // Protocol messages (revoke, ephemeral, etc.) — silent ACK
-        if (decoded.type === 'protocol') { _whaDbg('[DBG] DM_FILTER proto id=' + id); return; }
+        // Protocol messages — handle history sync and app-state key share before dropping
+        if (decoded.type === 'protocol') {
+          _whaDbg('[DBG] PROTO subtype=' + decoded.subtype + ' id=' + id);
+
+          // ── HISTORY_SYNC_NOTIFICATION ─────────────────────────────────────
+          if (decoded.subtype === 'history_sync' && decoded.historySyncNotification) {
+            this._handleHistorySync(decoded.historySyncNotification, id);
+          }
+
+          // ── APP_STATE_SYNC_KEY_SHARE ──────────────────────────────────────
+          if (decoded.subtype === 'app_state_sync_key_share' && decoded.appStateSyncKeyShare) {
+            this._handleAppStateSyncKeyShare(decoded.appStateSyncKeyShare);
+          }
+
+          return;
+        }
 
         this.emit('message', { id, from, participant, ts, decoded, node });
         this._sendReadReceipt(id, fromRaw, partRaw);
@@ -728,7 +749,15 @@ class WhalibmobClient extends EventEmitter {
       const plaintext = this._signal.senderKeyDecrypt(from, participant, cipherBuf);
       const decoded   = this._decodeMsg(plaintext);
       if (decoded.type === 'senderKeyDistribution') return;
-      if (decoded.type === 'protocol') return;
+      if (decoded.type === 'protocol') {
+        if (decoded.subtype === 'history_sync' && decoded.historySyncNotification) {
+          this._handleHistorySync(decoded.historySyncNotification, id);
+        }
+        if (decoded.subtype === 'app_state_sync_key_share' && decoded.appStateSyncKeyShare) {
+          this._handleAppStateSyncKeyShare(decoded.appStateSyncKeyShare);
+        }
+        return;
+      }
       this.emit('message', { id, from, participant, ts, decoded, isGroup: true, node });
       this._sendReadReceipt(id, fromRaw, partRaw);
     } catch (err) {
@@ -1020,6 +1049,14 @@ class WhalibmobClient extends EventEmitter {
       this._handlePrivacyTokenNotification(node);
     }
 
+    if (type === 'md-msg-hist') {
+      // Server signals that history sync data is available.
+      // The actual encrypted notification may arrive as:
+      //   (a) an encrypted <message> containing HistorySyncNotification (primary path, handled in _decryptDMMessage)
+      //   (b) inline in this notification node via an <enc> child (handle here)
+      this._handleMdMsgHistNotification(node);
+    }
+
     if (type === 'devices') {
       // Server push: a contact's linked device list changed (they linked or
       // unlinked a tablet, desktop, etc.).  Invalidate that phone's cache entry
@@ -1710,6 +1747,246 @@ class WhalibmobClient extends EventEmitter {
     })();
   }
 
+  // ─── History sync ─────────────────────────────────────────────────────────
+
+  /**
+   * _handleHistorySync — called when a decrypted DM protocol message contains
+   * subtype='history_sync' with a HistorySyncNotification.
+   *
+   * Fires asynchronously (fire-and-forget with error emission).
+   * Emits 'history_sync' on success, 'history_sync_error' on failure.
+   *
+   * @param {object} notification  Decoded HistorySyncNotification
+   * @param {string} msgId         Source message ID (for logging)
+   */
+  _handleHistorySync(notification, msgId) {
+    if (!notification) return;
+    const phone      = this._store && this._store.phoneNumber;
+    const sessionDir = this._sessionDir;
+
+    _whaDbg('[DBG] HIST_SYNC start syncType=' + notification.syncType +
+      ' progress=' + notification.progress +
+      ' chunk=' + notification.chunkOrder +
+      ' inline=' + !!(notification.initialHistBootstrapInlinePayload &&
+                       notification.initialHistBootstrapInlinePayload.length) +
+      ' msgId=' + msgId);
+
+    processHistorySyncNotification(notification, sessionDir, phone)
+      .then(result => {
+        _whaDbg('[DBG] HIST_SYNC done syncType=' + result.syncTypeName +
+          ' chats=' + result.chats.length +
+          ' contacts=' + result.contacts.length +
+          ' pushNames=' + (result.pushNames || []).length);
+
+        // Populate in-memory LID ↔ PN mappings from history sync data
+        if (result.lidPnMappings && result.lidPnMappings.length) {
+          for (const m of result.lidPnMappings) {
+            if (m.lidJid && m.pnJid) {
+              const lidUser = m.lidJid.split('@')[0].split(':')[0];
+              const pnUser  = m.pnJid.split('@')[0].split(':')[0];
+              if (lidUser && pnUser) {
+                this._lidToPn.set(lidUser, pnUser);
+                this._pnToLid.set(pnUser, lidUser);
+                if (this._signal && this._signal.store && this._signal.store.setLidMapping) {
+                  this._signal.store.setLidMapping(pnUser, lidUser);
+                }
+              }
+            }
+          }
+        }
+
+        // Seed TcTokenStore from history — populates trusted-contact tokens
+        // for all existing conversations so the first send after reconnect
+        // already carries a valid <tctoken> node (avoids error 463 on cold start).
+        this._seedTcTokensFromHistory(result.merged);
+
+        this.emit('history_sync', result);
+      })
+      .catch(err => {
+        _whaDbg('[DBG] HIST_SYNC_ERR ' + (err && err.message));
+        this.emit('history_sync_error', { err, notification });
+      });
+  }
+
+  /**
+   * _seedTcTokensFromHistory — called after each history sync chunk.
+   *
+   * Reads tcToken/tcTokenTimestamp/tcTokenSenderTimestamp from the merged
+   * history store and loads them into TcTokenStore so that the first outbound
+   * DM after reconnect already has a valid <tctoken> node attached.
+   *
+   * Without this, TcTokenStore starts empty on every new connection and the
+   * first send to every existing contact is treated as an anonymous reach-out
+   * by the WhatsApp server, accumulating toward the error-463 timelock.
+   *
+   * Rules:
+   *  - Only seeds tokens that are not already in TcTokenStore (existing entry wins).
+   *  - Skips expired tokens (no point loading a token we'd immediately discard).
+   *  - Storage key follows TcTokenStore convention: normalized bare JID.
+   *    For LID chats (jid ends in @lid) we use the lid JID directly.
+   *    For PN chats we try to look up the LID first (Baileys always stores under LID).
+   *
+   * @param {object|null} merged  - Return value of mergeHistoryToStore()
+   */
+  _seedTcTokensFromHistory(merged) {
+    if (!merged || !merged.chats) return;
+    if (!this._tcTokenStore) return;
+
+    const { normalizeJidForTcToken, tcTokenExpired } = require('./messages/TcTokenStore');
+
+    let seeded = 0;
+    for (const [jid, chat] of Object.entries(merged.chats)) {
+      // Only chats that actually have a token stored from history
+      if (!chat.tcToken) continue;
+
+      // Convert base64 string back to Buffer (mergeHistoryToStore stores as base64)
+      const tokenBuf = Buffer.from(chat.tcToken, 'base64');
+      if (!tokenBuf.length) continue;
+
+      const ts       = chat.tcTokenTimestamp      || 0;
+      const senderTs = chat.tcTokenSenderTimestamp || 0;
+
+      // Skip already-expired tokens — no use loading them
+      if (tcTokenExpired(ts)) {
+        _whaDbg('[DBG] SEED_TCTOKEN skip expired jid=' + jid + ' ts=' + ts);
+        continue;
+      }
+
+      // Resolve storage JID: Baileys always stores under LID.
+      // If this chat is a @lid jid, use it directly.
+      // If it's a PN jid, try to find its LID counterpart.
+      let storageJid;
+      if (jid.endsWith('@lid')) {
+        storageJid = normalizeJidForTcToken(jid);
+      } else {
+        const pnUser  = jid.split('@')[0].split(':')[0];
+        const lidUser = this._pnToLid && this._pnToLid.get(pnUser);
+        storageJid    = lidUser
+          ? normalizeJidForTcToken(lidUser + '@lid')
+          : normalizeJidForTcToken(jid);
+      }
+
+      // Don't overwrite a token that was already fetched live this session
+      const existing = this._tcTokenStore.get(storageJid);
+      if (existing && existing.token && existing.token.length &&
+          !tcTokenExpired(existing.timestamp)) {
+        _whaDbg('[DBG] SEED_TCTOKEN skip existing jid=' + storageJid);
+        continue;
+      }
+
+      // Set token + senderTimestamp atomically via the two TcTokenStore setters
+      this._tcTokenStore.setToken(storageJid, tokenBuf, ts);
+      if (senderTs) {
+        this._tcTokenStore.setSenderTimestamp(storageJid, senderTs);
+      }
+      seeded++;
+      _whaDbg('[DBG] SEED_TCTOKEN seeded jid=' + storageJid +
+        ' ts=' + ts + ' senderTs=' + senderTs + ' len=' + tokenBuf.length);
+    }
+
+    if (seeded > 0) {
+      _whaDbg('[DBG] SEED_TCTOKEN total seeded=' + seeded + ' from history');
+    }
+  }
+
+  /**
+   * _handleAppStateSyncKeyShare — saves app-state sync keys received in a
+   * ProtocolMessage (type=5 APP_STATE_SYNC_KEY_SHARE).
+   * These keys are needed to decrypt app-state patches in _syncAppState.
+   *
+   * @param {object} keyShare  Decoded AppStateSyncKeyShare { keys: [...] }
+   */
+  _handleAppStateSyncKeyShare(keyShare) {
+    if (!keyShare || !keyShare.keys || !keyShare.keys.length) return;
+    const phone      = this._store && this._store.phoneNumber;
+    const sessionDir = this._sessionDir;
+
+    _whaDbg('[DBG] APP_STATE_KEY_SHARE keys=' + keyShare.keys.length);
+
+    try {
+      saveAppStateSyncKeys(sessionDir, phone, keyShare);
+    } catch (e) {
+      _whaDbg('[DBG] APP_STATE_KEY_SHARE_SAVE_ERR ' + e.message);
+    }
+
+    this.emit('app_state_keys', { keys: keyShare.keys });
+  }
+
+  /**
+   * _handleMdMsgHistNotification — called when server sends a
+   * <notification type="md-msg-hist"> node.
+   *
+   * On mobile WhatsApp the primary history sync path is via encrypted DM
+   * protocol messages (HistorySyncNotification inside a ProtocolMessage type=6).
+   * This handler covers the secondary path where the server delivers the
+   * notification inline inside the notification node itself with an <enc> child,
+   * or simply signals availability so we emit the event.
+   *
+   * @param {object} node  Full BinaryNode of the notification
+   */
+  _handleMdMsgHistNotification(node) {
+    if (!node) return;
+    const attrs = node.attrs || {};
+
+    _whaDbg('[DBG] MD_MSG_HIST from=' + (attrs.from || '') + ' id=' + (attrs.id || ''));
+
+    // Check for inline HistorySyncNotification bytes in an <enc> child
+    // (some server versions deliver it this way)
+    const encNode = findChild(node, 'enc');
+    if (encNode) {
+      const encBuf = Buffer.isBuffer(encNode.content)
+        ? encNode.content
+        : (encNode.content ? Buffer.from(encNode.content) : null);
+
+      if (encBuf && encBuf.length > 0) {
+        // Try to decode directly as HistorySyncNotification (unencrypted path)
+        try {
+          const notification = decodeHistorySyncNotification(encBuf);
+          if (notification && (notification.directPath || notification.initialHistBootstrapInlinePayload)) {
+            _whaDbg('[DBG] MD_MSG_HIST inline notification directPath=' + notification.directPath);
+            this._handleHistorySync(notification, attrs.id || 'md-msg-hist');
+            return;
+          }
+        } catch (_) {}
+      }
+    }
+
+    // Emit raw event for the caller to inspect if needed
+    this.emit('md_msg_hist', { node, attrs });
+  }
+
+  /**
+   * getHistoryStore — load the persisted history store for this phone.
+   * Returns the parsed {phone}.history.json content or null if not yet synced.
+   *
+   * @returns {object|null}
+   */
+  getHistoryStore() {
+    if (!this._store || !this._store.phoneNumber) return null;
+    const fs   = require('fs');
+    const file = require('path').join(this._sessionDir, this._store.phoneNumber + '.history.json');
+    try {
+      if (!fs.existsSync(file)) return null;
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (_) { return null; }
+  }
+
+  /**
+   * getMessagesStore — load the persisted messages for this phone.
+   * Returns the parsed {phone}.messages.json content or null if not yet synced.
+   *
+   * @returns {object|null}
+   */
+  getMessagesStore() {
+    if (!this._store || !this._store.phoneNumber) return null;
+    const fs   = require('fs');
+    const file = require('path').join(this._sessionDir, this._store.phoneNumber + '.messages.json');
+    try {
+      if (!fs.existsSync(file)) return null;
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (_) { return null; }
+  }
+
   // ─── Public API ───────────────────────────────────────────────────────────
 
   setPresence(available) {