whalibmob 5.5.90 → 5.6.2

package/lib/Client.js

@@ -193,6 +193,11 @@ class WhalibmobClient extends EventEmitter {
     this._signal        = null;
     this._devMgr        = null;
     this._sessionDir    = opts.sessionDir || process.env.HOME + '/.waSession';
+    // 'mobile' — registered over SMS as the account's primary device (default,
+    // and what every existing caller gets). 'web' — linked to an existing
+    // account as a companion, via pairing code.
+    this._mode          = 'mobile';
+    this._webSessionFile = null;
     this._pingTimer               = null;
     this._keepTimer               = null;
     this._connected     = false;
@@ -296,6 +301,8 @@ class WhalibmobClient extends EventEmitter {
   }
 
   async _connectSocket() {
+    if (this._mode === 'web') return this._connectWebSocket();
+
     const socket = new NoiseSocket(this._store);
     this._socket = socket;
 
@@ -313,6 +320,406 @@ class WhalibmobClient extends EventEmitter {
     return socket;
   }
 
+  // ──────────────────────────────────────────────────────────────────────────
+  // WHATSAPP WEB (companion) MODE
+  //
+  // Same library, same public API, different way in. Instead of registering a
+  // number over SMS as the account's primary device, we link to an account that
+  // already exists — the way the web client and the desktop apps do. Everything
+  // above the connection is unchanged: the Signal layer, the sender, the group
+  // and media code all read the same store fields.
+  //
+  // Two things do differ once connected, and both are handled below:
+  //   · our own JID carries a device index, so we are no longer device 0 and
+  //     the account's phone becomes just another device we encrypt to;
+  //   · the primary ships history over, which a primary device never receives.
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Connect as a companion device.
+   *
+   * If the session has never been paired this resolves as soon as the encrypted
+   * channel is up, leaving the caller to call requestPairingCode(). If it has,
+   * it behaves like connect(): resolves once the server sends <success>.
+   *
+   * @param {string} phoneNumber  account phone number, digits only
+   * @param {object} [opts]       { syncFullHistory, browser }
+   */
+  async connectWeb(phoneNumber, opts) {
+    return this.initWeb(phoneNumber, opts);
+  }
+
+  async initWeb(phoneNumber, opts) {
+    opts = opts || {};
+    phoneNumber = String(phoneNumber).replace(/\D/g, '');
+    this._phoneNumber = phoneNumber;
+    this._mode = 'web';
+
+    const { createNewWebStore, loadWebStore, saveWebStore, webSessionPath } =
+      require('./WebStore');
+
+    this._webSessionFile = webSessionPath(this._sessionDir, phoneNumber);
+    this._store = loadWebStore(this._webSessionFile) || createNewWebStore(phoneNumber);
+
+    if (opts.syncFullHistory !== undefined) this._store.syncFullHistory = !!opts.syncFullHistory;
+    if (opts.browser) this._store.browser = opts.browser;
+    saveWebStore(this._store, this._webSessionFile);
+
+    // Signal state lives in its own files so a web link and an SMS
+    // registration for the same number never share sessions or pre-keys.
+    const signalFile  = path.join(this._sessionDir, `${phoneNumber}.web.signal.json`);
+    const skFile      = path.join(this._sessionDir, `${phoneNumber}.web.sk.json`);
+    const tcTokenFile = path.join(this._sessionDir, `${phoneNumber}.web.tctoken.json`);
+
+    const { TcTokenStore } = require('./messages/TcTokenStore');
+    this._tcTokenStore = new TcTokenStore(tcTokenFile);
+
+    this._signal = SignalProtocol.fromStore(this._store, signalFile, skFile);
+    this._devMgr = new DeviceManager(this);
+    this._devMgr.attachSession(this._sessionDir, phoneNumber + '.web');
+
+    const persistedLid = this._signal.store.getLidMappings
+      ? this._signal.store.getLidMappings() : {};
+    for (const [phone, lid] of Object.entries(persistedLid)) {
+      this._pnToLid.set(phone, lid);
+      this._lidToPn.set(lid, phone);
+    }
+
+    if (this._store.me && this._store.me.lid) this._myLid = this._store.me.lid;
+
+    await this._connectWebSocket();
+    return this;
+  }
+
+  _saveWebStore() {
+    if (this._mode !== 'web' || !this._webSessionFile) return;
+    const { saveWebStore } = require('./WebStore');
+    saveWebStore(this._store, this._webSessionFile);
+  }
+
+  async _connectWebSocket() {
+    const { encodeCompanionRegisterPayload, encodeCompanionLoginPayload } =
+      require('./webproto');
+
+    const store      = this._store;
+    const registered = !!store.registered && !!(store.me && store.me.id);
+
+    const payloadOpts = {
+      version:         store.webVersion,
+      browser:         store.browser,
+      countryCode:     'US',
+      pushName:        store.name && store.name !== 'User' ? store.name : undefined,
+      syncFullHistory: store.syncFullHistory !== false,
+      registrationId:  store.registrationId,
+      identityKeyPair: store.identityKeyPair,
+      signedPreKey:    store.signedPreKey
+    };
+
+    const socket = new NoiseSocket(store, {
+      transport:     'web',
+      // An unpaired companion never gets <success> on this connection — the
+      // server answers with pair-device and waits for a human to act.
+      expectSuccess: registered,
+      buildPayload:  () => registered
+        ? encodeCompanionLoginPayload(Object.assign({}, payloadOpts, {
+            username: store.phoneNumber,
+            device:   store.deviceIndex || 0
+          }))
+        : encodeCompanionRegisterPayload(payloadOpts)
+    });
+
+    this._socket = socket;
+    this._sender = new MessageSender(this);
+
+    socket.on('open',    (sn) => this._onOpen(sn));
+    socket.on('secured', ()   => {
+      _whaDbg('[DBG] WEB_CHANNEL_SECURED — awaiting pairing');
+      this.emit('web_ready_for_pairing');
+    });
+    socket.on('node',  node => this._onNode(node));
+    socket.on('close', ()   => this._onClose());
+    socket.on('error', err  => this.emit('error', err));
+
+    await socket.connect();
+    return socket;
+  }
+
+  /**
+   * Ask WhatsApp for an 8-character pairing code.
+   *
+   * The account owner enters it on their phone under
+   * Settings → Linked Devices → Link a device → Link with phone number instead.
+   * The code is a password, not an identifier: it never travels to the server
+   * in the clear, and both sides run it through PBKDF2 to wrap the ephemeral
+   * keys they exchange.
+   *
+   * Resolves with the code as soon as the request is on the wire. The link
+   * itself completes later — wait for the 'paired' or 'open' event.
+   *
+   * @param {string} [phoneNumber]  defaults to the number initWeb was given
+   * @param {string} [customCode]   exactly 8 characters, if you want to choose
+   * @returns {Promise<string>}
+   */
+  async requestPairingCode(phoneNumber, customCode) {
+    if (this._mode !== 'web') {
+      throw new Error('requestPairingCode is only available in web mode — call connectWeb() first');
+    }
+    if (!this._socket || !this._socket.secured) {
+      throw new Error('Not connected — call connectWeb() before requesting a pairing code');
+    }
+    if (this._store.registered) {
+      throw new Error('This session is already linked — no pairing code needed');
+    }
+
+    const { generatePairingCode, buildWrappedEphemeralPub, generateEphemeralKeyPair } =
+      require('./PairingCode');
+    const { platformTypeFor } = require('./webproto');
+
+    if (customCode != null && String(customCode).length !== 8) {
+      throw new Error('A custom pairing code must be exactly 8 characters');
+    }
+
+    const phone = String(phoneNumber || this._phoneNumber || this._store.phoneNumber)
+      .replace(/\D/g, '');
+    if (!phone) throw new Error('requestPairingCode: a phone number is required');
+
+    const code = customCode ? String(customCode).toUpperCase() : generatePairingCode();
+
+    // A fresh ephemeral pair per attempt: a code that was requested and never
+    // used must not be able to complete a later exchange.
+    this._store.pairingEphemeralKeyPair = generateEphemeralKeyPair();
+    this._store.pairingCode = code;
+    this._store.phoneNumber = phone;
+    this._store.me = { id: phone + '@s.whatsapp.net', name: '~', lid: null };
+    this._saveWebStore();
+
+    const browser  = this._store.browser || ['Ubuntu', 'Chrome', '120.0.0.0'];
+    const wrapped  = await buildWrappedEphemeralPub(code, this._store.pairingEphemeralKeyPair.public);
+
+    // The bare 32-byte curve point, not the 33-byte Signal form.
+    //
+    // whalibmob stores every public key with the 0x05 type prefix, and the
+    // Noise handshake strips it on the way out. This node had no such strip, so
+    // the primary would have hashed 33 bytes where it expected 32 and the link
+    // would fail with nothing to point at.
+    const { stripKeyPrefix } = require('./PairingCode');
+    const noisePub = stripKeyPrefix(this._store.noiseKeyPair.public);
+
+    const node = new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'set',
+      xmlns: 'md'
+    }, [
+      new BinaryNode('link_code_companion_reg', {
+        jid:   this._store.me.id,
+        stage: 'companion_hello',
+        should_show_push_notification: 'true'
+      }, [
+        new BinaryNode('link_code_pairing_wrapped_companion_ephemeral_pub', {}, wrapped),
+        new BinaryNode('companion_server_auth_key_pub', {}, noisePub),
+        new BinaryNode('companion_platform_id', {}, Buffer.from(
+          String(platformTypeFor(browser[1])), 'utf8')),
+        new BinaryNode('companion_platform_display', {}, Buffer.from(
+          `${browser[1]} (${browser[0]})`, 'utf8')),
+        new BinaryNode('link_code_pairing_nonce', {}, Buffer.from('0', 'utf8'))
+      ])
+    ]);
+
+    _whaDbg('[DBG] REQUEST_PAIRING_CODE phone=' + phone + ' code=' + code);
+    this._socket.sendNode(node);
+    this.emit('pairing_code', { code, phoneNumber: phone });
+    return code;
+  }
+
+  /**
+   * Stage 3 of the pairing exchange, driven by the server.
+   *
+   * Arrives once the account owner has typed the code into their phone. We
+   * unwrap the primary's ephemeral key with the key derived from that code, do
+   * the two Diffie-Hellmans, and store adv_secret — the key pair-success will
+   * be verified under.
+   */
+  async _handleCompanionFinish(node) {
+    const { buildCompanionFinishBundle } = require('./PairingCode');
+
+    const reg = findChild(node, 'link_code_companion_reg');
+    if (!reg) return;
+
+    const childBuf = (desc) => {
+      const c = findChild(reg, desc);
+      if (!c) return null;
+      return Buffer.isBuffer(c.content) ? c.content
+           : ArrayBuffer.isView(c.content) ? Buffer.from(c.content)
+           : typeof c.content === 'string' ? Buffer.from(c.content, 'utf8')
+           : null;
+    };
+
+    const ref                = childBuf('link_code_pairing_ref');
+    const primaryIdentityPub = childBuf('primary_identity_pub');
+    const wrappedEphemeral   = childBuf('link_code_pairing_wrapped_primary_ephemeral_pub');
+
+    if (!ref || !primaryIdentityPub || !wrappedEphemeral) {
+      _whaDbg('[DBG] COMPANION_FINISH missing fields — aborting');
+      this.emit('error', new Error('Pairing failed: incomplete companion_finish from server'));
+      return;
+    }
+
+    try {
+      const { advSecretKey, wrappedKeyBundle } = await buildCompanionFinishBundle({
+        pairingCode:                this._store.pairingCode,
+        pairingEphemeralPrivate:    this._store.pairingEphemeralKeyPair.private,
+        primaryEphemeralPubWrapped: wrappedEphemeral,
+        primaryIdentityPub,
+        identityKeyPair:            this._store.identityKeyPair
+      });
+
+      this._store.advSecretKey = advSecretKey;
+      this._saveWebStore();
+      _whaDbg('[DBG] COMPANION_FINISH adv_secret derived');
+
+      // Baileys awaits this one rather than firing and forgetting, so a server
+      // rejection surfaces as an error here instead of as a silent stall
+      // waiting for a pair-success that is never coming.
+      const finishResult = await this._sendIq(new BinaryNode('iq', {
+        to:    's.whatsapp.net',
+        type:  'set',
+        id:    this._genMsgId(),
+        xmlns: 'md'
+      }, [
+        new BinaryNode('link_code_companion_reg', {
+          jid:   this._store.me.id,
+          stage: 'companion_finish'
+        }, [
+          new BinaryNode('link_code_pairing_wrapped_key_bundle', {}, wrappedKeyBundle),
+          new BinaryNode('companion_identity_public', {},
+            require('./PairingCode').stripKeyPrefix(this._store.identityKeyPair.public)),
+          new BinaryNode('link_code_pairing_ref', {}, ref)
+        ])
+      ]));
+
+      if (finishResult && finishResult.attrs && finishResult.attrs.type === 'error') {
+        const errNode = findChild(finishResult, 'error');
+        const code = errNode && errNode.attrs && errNode.attrs.code;
+        throw new Error('server rejected companion_finish' + (code ? ' (' + code + ')' : ''));
+      }
+      _whaDbg('[DBG] COMPANION_FINISH accepted — awaiting pair-success');
+    } catch (err) {
+      _whaDbg('[DBG] COMPANION_FINISH_ERR ' + (err && err.message));
+      this.emit('error', new Error('Pairing failed: ' + (err && err.message)));
+    }
+  }
+
+  /**
+   * <iq><pair-success> — the primary has authorised us.
+   *
+   * Verify what it sent, counter-sign it, reply, and persist. The server closes
+   * the connection right after with a 515; the reconnect logs in normally and
+   * that is when history starts arriving.
+   */
+  _handlePairSuccess(node) {
+    const { configureSuccessfulPairing } = require('./CompanionPairing');
+    try {
+      const result = configureSuccessfulPairing(node, {
+        advSecretKey:    this._store.advSecretKey,
+        identityKeyPair: this._store.identityKeyPair
+      }, BinaryNode);
+
+      this._store.me          = result.me;
+      this._store.deviceIndex = result.deviceIndex;
+      this._store.platform    = result.platform;
+      // The same field the mobile path fills from <success>: the signed device
+      // identity that rides on outgoing pkmsg stanzas.
+      this._store.advIdentity = result.accountEnc;
+      this._store.registered  = true;
+      this._store.pairingCode = null;
+      if (result.me && result.me.name) this._store.name = result.me.name;
+      this._saveWebStore();
+
+      if (result.me && result.me.lid) {
+        this._myLid = result.me.lid;
+        const lidUser = String(result.me.lid).split('@')[0].split(':')[0];
+        const pnUser  = String(result.me.id).split('@')[0].split(':')[0];
+        this._lidToPn.set(lidUser, pnUser);
+        this._pnToLid.set(pnUser, lidUser);
+      }
+
+      this._socket.sendNode(result.reply);
+      this._sendUnifiedSession();
+      _whaDbg('[DBG] PAIR_SUCCESS jid=' + result.me.id + ' lid=' + result.me.lid +
+        ' device=' + result.deviceIndex);
+      this.emit('paired', {
+        jid:         result.me.id,
+        lid:         result.me.lid,
+        deviceIndex: result.deviceIndex,
+        platform:    result.platform
+      });
+    } catch (err) {
+      _whaDbg('[DBG] PAIR_SUCCESS_ERR ' + (err && err.message));
+      this.emit('error', err);
+    }
+  }
+
+  /**
+   * <iq><pair-device> — the QR path.
+   *
+   * We do not display QR codes, but the node still has to be acknowledged or
+   * the server keeps re-sending refs. The refs are surfaced as an event so a
+   * caller that wants to render a QR can.
+   */
+  _handlePairDevice(node) {
+    const id = node.attrs && node.attrs.id;
+    if (id) {
+      this._socket.sendNode(new BinaryNode('iq', {
+        to: 's.whatsapp.net', type: 'result', id
+      }, null));
+    }
+    const pairDevice = findChild(node, 'pair-device');
+    const refs = pairDevice && Array.isArray(pairDevice.content)
+      ? pairDevice.content
+          .filter(c => c && c.description === 'ref')
+          .map(c => (Buffer.isBuffer(c.content) ? c.content.toString('utf8') : String(c.content)))
+      : [];
+    this.emit('pair_device', { refs });
+  }
+
+  /**
+   * The JID this device sends as.
+   *
+   * A primary is device 0 and its JID is the bare number. A companion occupies
+   * a numbered slot, and the account's phone is then a peer we encrypt to like
+   * any other linked device — which is exactly the difference the fan-out code
+   * needs to know about.
+   */
+  _ownDeviceJid() {
+    const phone = String(this._store.phoneNumber);
+    const idx   = (this._mode === 'web' && this._store.deviceIndex) || 0;
+    return idx > 0 ? `${phone}:${idx}@s.whatsapp.net` : `${phone}@s.whatsapp.net`;
+  }
+
+  // <ib><unified_session/> — the telemetry ping a web client emits after
+  // 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.
+  _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();
+      this._socket.sendNode(new BinaryNode('ib', {}, [
+        new BinaryNode('unified_session', { id }, null)
+      ]));
+    } catch (_) {}
+  }
+
+  /** Same, in LID space. */
+  _ownDeviceLidJid() {
+    if (!this._myLid) return null;
+    const lidUser = String(this._myLid).split('@')[0].split(':')[0];
+    const idx = (this._mode === 'web' && this._store.deviceIndex) || 0;
+    return idx > 0 ? `${lidUser}:${idx}@lid` : `${lidUser}@lid`;
+  }
+
   disconnect() {
     this._reconnecting = false;
     this._reconnectTry = 0;
@@ -372,6 +779,9 @@ class WhalibmobClient extends EventEmitter {
     this._requestMediaConnection();
     this._uploadPreKeys();
 
+    // Same telemetry ping the web client sends on every completed login.
+    this._sendUnifiedSession();
+
     // Warm the privacy settings so read receipts respect them from the first
     // message rather than from whenever something first asks for them.
     this.queryPrivacySettings({ force: true }).catch(err =>
@@ -457,18 +867,34 @@ class WhalibmobClient extends EventEmitter {
       if (bytes && bytes.length > 0) {
         this._store.advIdentity = bytes;
         // Persist to session file so it survives restart
-        const sessionFile = path.join(
-          this._sessionDir,
-          `${this._store.phoneNumber}.json`
-        );
-        try {
-          const { saveStore } = require('./Store');
-          saveStore(this._store, sessionFile);
-        } catch (_) {}
+        if (this._mode === 'web') {
+          this._saveWebStore();
+        } else {
+          const sessionFile = path.join(
+            this._sessionDir,
+            `${this._store.phoneNumber}.json`
+          );
+          try {
+            const { saveStore } = require('./Store');
+            saveStore(this._store, sessionFile);
+          } catch (_) {}
+        }
       }
     } else if (this._store.advIdentity) {
       // Already have it persisted from a previous session — keep using it
     }
+
+    // A companion learns its own LID from pair-success, not from <success>, so
+    // keep what pairing established rather than leaving it unset on reconnect.
+    if (this._mode === 'web') {
+      if (!this._myLid && this._store.me && this._store.me.lid) {
+        this._myLid = this._store.me.lid;
+      }
+      if (attrs.lid && this._store.me) {
+        this._store.me.lid = String(attrs.lid);
+        this._saveWebStore();
+      }
+    }
   }
 
   // ── Feature 3 (part A): Activate the connection ────────────────────────────
@@ -645,10 +1071,31 @@ class WhalibmobClient extends EventEmitter {
     else if (tag === 'ib')           this._handleIb(node);
     else if (tag === 'success')      this.emit('session_refresh', { node }); // late success (re-auth)
     else if (tag === 'failure')      this._handleFailure(node);
-    else if (tag === 'stream:error') this.emit('stream_error', { reason: node.attrs && node.attrs.reason });
+    else if (tag === 'stream:error') this._handleStreamError(node);
     else                             this.emit('node', node);
   }
 
+  // A stream error ends the connection; the reconnect in _onClose picks it up.
+  //
+  // 515 is not a failure. The server sends it immediately after a companion
+  // finishes pairing to say "you are linked now, start over as a normal
+  // client" — the next connection carries the login payload instead of the
+  // pairing bundle, and that is the one that receives history.
+  _handleStreamError(node) {
+    const attrs  = (node && node.attrs) || {};
+    const code   = attrs.code ? String(attrs.code) : null;
+    const reason = attrs.reason || code || 'unknown';
+
+    if (code === '515') {
+      _whaDbg('[DBG] STREAM_ERROR 515 — restart required after pairing, reconnecting');
+      this.emit('restart_required', { reason });
+      return;
+    }
+
+    _whaDbg('[DBG] STREAM_ERROR code=' + code + ' reason=' + reason);
+    this.emit('stream_error', { reason, code });
+  }
+
   // ─── IQ handling ──────────────────────────────────────────────────────────
 
   _handleIq(node) {
@@ -656,6 +1103,18 @@ class WhalibmobClient extends EventEmitter {
     const type  = node.attrs && node.attrs.type;
     const xmlns = node.attrs && node.attrs.xmlns;
 
+    // Companion pairing — these arrive unsolicited, so they are checked before
+    // the pending-IQ table rather than after it.
+    //
+    // pair-device is matched on type=set; pair-success is matched on any type,
+    // the way Baileys distinguishes them ('CB:iq,type:set,pair-device' against
+    // a bare 'CB:iq,,pair-success'). Requiring type=set on pair-success would
+    // drop the stanza that completes the link.
+    if (this._mode === 'web') {
+      if (type === 'set' && findChild(node, 'pair-device')) { this._handlePairDevice(node);  return; }
+      if (findChild(node, 'pair-success'))                  { this._handlePairSuccess(node); return; }
+    }
+
     // Resolve pending IQ
     if (id) {
       const handler = this._pendingIqs.get(id);
@@ -1099,6 +1558,69 @@ class WhalibmobClient extends EventEmitter {
     return base;
   }
 
+  // The key a privacy token is stored and looked up under.
+  //
+  // Both references resolve it to the contact's LID and fall back to the plain
+  // JID only when no LID is known — whatsmeow's resolveTCTokenStorageLID and
+  // Baileys' resolveTcTokenJid are the same three lines:
+  //
+  //     if (isLidUser(jid)) return jid
+  //     const lid = await getLIDForPN(jid)
+  //     return lid ?? jid
+  //
+  // whalibmob resolved it on the receiving side but not on the sending side,
+  // which put the two halves out of step: a token a contact issued us arrived
+  // on a privacy_token notification and was filed under their LID, while every
+  // send looked it up under their phone JID and found nothing. The token was
+  // therefore never attached to anything, and the server kept counting our
+  // messages as anonymous reach-outs — which is what error 463 is.
+  _resolveTcTokenJid(jid) {
+    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;
+  }
+
+  // The JID a token is *issued* to, which is not the JID it is *stored* under.
+  //
+  // Storage is always the LID. Issuance follows AB prop 14303
+  // (lid_trusted_token_issue_to_lid), whose WA Web default is off — so the IQ
+  // names the phone JID. Baileys implements exactly this in resolveIssuanceJid
+  // and defaults the prop to false; whatsmeow issues to the LID instead. We
+  // follow WA Web, and more importantly we now follow it in one place: the
+  // send path, the 463 recovery and the post-identity-change re-issue used to
+  // each pick a different address family for the same contact.
+  _resolveTcTokenIssuanceJid(jid) {
+    const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
+    const norm = normalizeJidForTcToken(jid);
+    if (!norm.endsWith('@lid')) return norm;
+    const pnUser = this._lidToPn && this._lidToPn.get(norm.split('@')[0]);
+    return pnUser ? pnUser + '@s.whatsapp.net' : norm;
+  }
+
+  // The one way to read a token that is safe to put on the wire.
+  //
+  // whatsmeow funnels every attach site through ensureTCToken, which returns
+  // nothing for an expired token. whalibmob had the expiry check on the message
+  // path only; presence subscribe, group create, participant add and the
+  // profile-picture query each tested `token.length` and nothing else, so once
+  // a token aged past the 28-day window those four kept sending it. Same rule
+  // everywhere now, and the dead token gets cleared on the way out.
+  _tcTokenFor(jid) {
+    if (!this._tcTokenStore) return null;
+    const { tcTokenExpired } = require('./messages/TcTokenStore');
+    const tcJid = this._resolveTcTokenJid(jid);
+    const entry = this._tcTokenStore.get(tcJid);
+    if (!entry || !entry.token || !entry.token.length) return null;
+    if (tcTokenExpired(entry.timestamp)) {
+      this._tcTokenStore.clearToken(tcJid);
+      _whaDbg('[DBG] TCTOKEN_EXPIRED jid=' + tcJid + ' — cleared');
+      return null;
+    }
+    return entry.token;
+  }
+
   // True when a JID names this account, in either address family.
   _isOwnUser(jid) {
     if (!jid) return false;
@@ -1344,6 +1866,11 @@ class WhalibmobClient extends EventEmitter {
       this._handlePrivacyTokenNotification(node);
     }
 
+    if (type === 'link_code_companion_reg') {
+      // The account owner just typed our pairing code into their phone.
+      this._handleCompanionFinish(node);
+    }
+
     if (type === 'md-msg-hist') {
       // Server signals that history sync data is available.
       // The actual encrypted notification may arrive as:
@@ -1953,6 +2480,7 @@ class WhalibmobClient extends EventEmitter {
   _storeTcTokenFromIqResult(result, fallbackJid, issueTs, opts) {
     const saveSenderTs = !opts || opts.saveSenderTs !== false; // default true
     if (!this._tcTokenStore) return;
+    const { isRegularTcTokenUser } = require('./messages/TcTokenStore');
 
     // ── Debug: dump result structure so we can trace server response ─────────
     if (!result) {
@@ -2002,10 +2530,21 @@ class WhalibmobClient extends EventEmitter {
           // → always prefer fallbackJid; only fall back to a.jid when fallbackJid is absent
           const jid = fallbackJid || String(a.jid);
           const t   = a.t   ? parseInt(String(a.t), 10) : issueTs;
+          // Baileys drops anything that is not a regular user here — the guard
+          // is against a malformed or spoofed notification filing a token under
+          // the PSA account or a bot.
+          if (!isRegularTcTokenUser(jid)) {
+            _whaDbg('[DBG] STORE_TCTOKEN skipped non-user jid=' + jid);
+            continue;
+          }
           if (bytes && bytes.length) {
-            this._tcTokenStore.setToken(jid, bytes, t);
-            tokenStoredCount++;
-            _whaDbg('[DBG] TCTOKEN_STORED jid=' + jid + ' t=' + t + ' len=' + bytes.length);
+            // setToken refuses a timestamp-less or older-than-stored token.
+            if (this._tcTokenStore.setToken(jid, bytes, t)) {
+              tokenStoredCount++;
+              _whaDbg('[DBG] TCTOKEN_STORED jid=' + jid + ' t=' + t + ' len=' + bytes.length);
+            } else {
+              _whaDbg('[DBG] STORE_TCTOKEN rejected (no/older timestamp) jid=' + jid + ' t=' + t);
+            }
           } else {
             _whaDbg('[DBG] STORE_TCTOKEN token node has no bytes jid=' + jid);
           }
@@ -2021,7 +2560,9 @@ class WhalibmobClient extends EventEmitter {
     // ── we flood the server with privacy IQs.                            ─────
     // ── For incoming privacy_token notifications saveSenderTs=false so  ─────
     // ── we don't overwrite our own send-dedupe timestamp with the peer's ─────
-    if (saveSenderTs && issueTs != null) {
+    // Same user gate as the token itself — no dedupe row for the PSA account
+    // or a bot, since we never issue to them in the first place.
+    if (saveSenderTs && issueTs != null && isRegularTcTokenUser(fallbackJid)) {
       try {
         this._tcTokenStore.setSenderTimestamp(fallbackJid, issueTs);
         _whaDbg('[DBG] SENDER_TS_SAVED jid=' + fallbackJid + ' ts=' + issueTs +
@@ -2081,11 +2622,9 @@ class WhalibmobClient extends EventEmitter {
       // from = LID_USER@s.whatsapp.net — WA sends LID notifications this way.
       // The user part is already the LID user; convert domain to @lid.
       storageJid = fromUser + '@lid';
-    } else if (this._pnToLid && this._pnToLid.has(fromUser)) {
-      // from is a PN → convert to LID for storage (Baileys always stores under LID)
-      storageJid = this._pnToLid.get(fromUser) + '@lid';
     } else {
-      storageJid = normalizeJidForTcToken(rawFrom);
+      // Same resolver the send side uses, so both halves agree on the key.
+      storageJid = this._resolveTcTokenJid(rawFrom);
     }
 
     _whaDbg('[DBG] PRIVACY_TOKEN_NOTIF storageJid=' + storageJid);
@@ -2112,11 +2651,7 @@ class WhalibmobClient extends EventEmitter {
 
     void (async () => {
       try {
-        // Resolve storage JID: PN→LID if available, otherwise use from as-is
-        const fromNorm = normalizeJidForTcToken(from);
-        const fromUser = fromNorm.split('@')[0];
-        const lidUser  = this._pnToLid && this._pnToLid.get(fromUser);
-        const tcJid    = lidUser ? (lidUser + '@lid') : fromNorm;
+        const tcJid = this._resolveTcTokenJid(from);
 
         const entry    = this._tcTokenStore.get(tcJid);
         const senderTs = entry && entry.senderTimestamp;
@@ -2128,9 +2663,15 @@ class WhalibmobClient extends EventEmitter {
         _whaDbg('[DBG] REISSUE_TC_TOKEN_AFTER_IDENTITY_CHANGE jid=' + tcJid +
           ' prevSenderTs=' + senderTs);
 
-        const issueTs = Math.floor(Date.now() / 1000);
-        const result  = await this._issuePrivacyTokens(tcJid, issueTs);
-        this._storeTcTokenFromIqResult(result, tcJid, issueTs);
+        // Baileys re-issues with the *previous* senderTimestamp, not a fresh
+        // one, and stores the result without touching the dedupe state. That
+        // matters: this is a repair of an existing grant after the peer's
+        // device changed, not a new grant, so it must not move the 7-day
+        // bucket that governs regular issuance. We were stamping it with
+        // Date.now(), which silently skipped the next scheduled issuance.
+        const issueJid = this._resolveTcTokenIssuanceJid(from);
+        const result   = await this._issuePrivacyTokens(issueJid, senderTs);
+        this._storeTcTokenFromIqResult(result, tcJid, senderTs, { saveSenderTs: false });
       } catch (e) {
         _whaDbg('[DBG] REISSUE_TC_TOKEN_ERR from=' + from +
           ' err=' + (e && e.message));
@@ -2152,7 +2693,12 @@ class WhalibmobClient extends EventEmitter {
    */
   _handleHistorySync(notification, msgId) {
     if (!notification) return;
-    const phone      = this._store && this._store.phoneNumber;
+    // Web-mode history lands in its own files. A number can be registered over
+    // SMS and separately linked as a companion, and only the companion ever
+    // receives history — merging the two would be merging different accounts'
+    // views of the same number.
+    const phone = (this._store && this._store.phoneNumber) +
+                  (this._mode === 'web' ? '.web' : '');
     const sessionDir = this._sessionDir;
 
     _whaDbg('[DBG] HIST_SYNC start syncType=' + notification.syncType +
@@ -2539,15 +3085,13 @@ class WhalibmobClient extends EventEmitter {
   subscribeToPresence(jids) {
     if (!this._socket || !this._connected) return;
     const arr = Array.isArray(jids) ? jids : [jids];
-    const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
+    const { isRegularTcTokenUser } = require('./messages/TcTokenStore');
     for (const raw of arr) {
       const jid   = makeJid(raw);
-      const entry = this._tcTokenStore && this._tcTokenStore.get(
-        normalizeJidForTcToken(jid)
-      );
-      const children = (entry && entry.token && entry.token.length)
-        ? [new BinaryNode('tctoken', {}, entry.token)]
-        : null;
+      // Groups and newsletters have no privacy token; Baileys guards the same
+      // way before building the node.
+      const token = isRegularTcTokenUser(jid) ? this._tcTokenFor(jid) : null;
+      const children = token ? [new BinaryNode('tctoken', {}, token)] : null;
       this._socket.sendNode(new BinaryNode('presence', {
         to:   jidStrToObj(jid),
         type: 'subscribe'
@@ -2682,12 +3226,8 @@ class WhalibmobClient extends EventEmitter {
       iqAttrs = { id: this._genMsgId(), xmlns: 'w:g2', to: jidStrToObj(jidFull), type: 'get' };
       content = [new BinaryNode('pictures', {}, [new BinaryNode('picture', attrs, null)])];
     } else {
-      const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
-      const entry = this._tcTokenStore &&
-        this._tcTokenStore.get(normalizeJidForTcToken(jidFull));
-      const picChildren = (entry && entry.token && entry.token.length)
-        ? [new BinaryNode('tctoken', {}, entry.token)]
-        : null;
+      const picToken    = this._tcTokenFor(jidFull);
+      const picChildren = picToken ? [new BinaryNode('tctoken', {}, picToken)] : null;
       iqAttrs = {
         id:     this._genMsgId(),
         xmlns:  'w:profile:picture',
@@ -2735,7 +3275,7 @@ class WhalibmobClient extends EventEmitter {
     const info = await this.queryPictureInfo(jid, opts);
     if (!info || !info.url) return null;
     const { httpGetBuffer } = require('./MediaService');
-    return httpGetBuffer(info.url);
+    return httpGetBuffer(info.url, { web: this._mode === 'web' });
   }
 
   // Parse the <list> a blocklist query or update comes back with.
@@ -3007,26 +3547,39 @@ class WhalibmobClient extends EventEmitter {
     }
 
     const ownJid = String(this._store.phoneNumber) + '@s.whatsapp.net';
-    let recipients;
+    let recipients, source;
 
     if (privacy.type === 'whitelist') {
       recipients = privacy.list.slice();
+      source = 'whitelist';
     } else {
-      const hist = this.getHistoryStore();
-      const contacts = (hist && hist.contacts) ? Object.keys(hist.contacts) : [];
-      // Only real contacts — an entry the history sync created purely to hold a
-      // push name is not somebody you have in your address book.
-      const named = contacts.filter(jid => {
+      const hist = this.getHistoryStore() || {};
+      const isPerson = (jid) => !jid.endsWith('@g.us') && !jid.endsWith('@broadcast') &&
+        !jid.endsWith('@newsletter') && !this._isOwnUser(jid);
+
+      // Contacts proper: entries the history sync gave a name to.
+      const contacts = Object.keys(hist.contacts || {}).filter(jid => {
         const c = hist.contacts[jid];
-        return c && (c.name || c.displayName) && !jid.endsWith('@g.us') &&
-          !jid.endsWith('@broadcast');
+        return c && (c.name || c.displayName) && isPerson(jid);
       });
+
+      // A named contact list is what WhatsApp itself posts to. When history has
+      // not brought one — a fresh session, or a sync that carried chats without
+      // names — the people you actually have conversations with are the next
+      // best thing, and far better than posting to nobody.
+      let pool = contacts;
+      source = 'contacts';
+      if (pool.length === 0) {
+        pool = Object.keys(hist.chats || {}).filter(isPerson);
+        source = 'chats';
+      }
+
       const blocked = new Set(privacy.type === 'blacklist' ? privacy.list : []);
-      recipients = named.filter(jid => !blocked.has(jid));
+      recipients = pool.filter(jid => !blocked.has(jid));
     }
 
     if (!recipients.some(j => this._isOwnUser(j))) recipients.push(ownJid);
-    _whaDbg('[DBG] STATUS_RECIPIENTS type=' + privacy.type +
+    _whaDbg('[DBG] STATUS_RECIPIENTS type=' + privacy.type + ' source=' + source +
       ' count=' + recipients.length);
     return recipients;
   }
@@ -3756,7 +4309,6 @@ class WhalibmobClient extends EventEmitter {
   async createGroup(subject, participants, opts) {
     opts = opts || {};
     const id       = this._genMsgId();
-    const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
     // participant nodes MUST use attr `jid`, not `value`
     const partNodes = (participants || []).map(p => {
       const jid   = makeJid(p);
@@ -3765,11 +4317,8 @@ class WhalibmobClient extends EventEmitter {
         const pn = this._lidToPn.get(jid.split('@')[0].split(':')[0]);
         if (pn) attrs.phone_number = jidStrToObj(pn + '@s.whatsapp.net');
       }
-      const entry = this._tcTokenStore &&
-        this._tcTokenStore.get(normalizeJidForTcToken(jid));
-      const children = (entry && entry.token && entry.token.length)
-        ? [new BinaryNode('privacy', {}, entry.token)]
-        : null;
+      const token    = this._tcTokenFor(jid);
+      const children = token ? [new BinaryNode('privacy', {}, token)] : null;
       return new BinaryNode('participant', attrs, children);
     });
 
@@ -3876,7 +4425,6 @@ class WhalibmobClient extends EventEmitter {
   async _groupParticipantAction(groupJid, action, jids) {
     const gJid = makeJid(groupJid);
     const arr  = Array.isArray(jids) ? jids : [jids];
-    const { normalizeJidForTcToken } = require('./messages/TcTokenStore');
     // Same shape whatsmeow's UpdateGroupParticipants builds: binary JIDs, and on
     // an add, the phone number behind a LID plus our privacy token for them.
     const participantNodes = arr.map(j => {
@@ -3888,11 +4436,8 @@ class WhalibmobClient extends EventEmitter {
           const pn = this._lidToPn.get(jid.split('@')[0].split(':')[0]);
           if (pn) attrs.phone_number = jidStrToObj(pn + '@s.whatsapp.net');
         }
-        const entry = this._tcTokenStore &&
-          this._tcTokenStore.get(normalizeJidForTcToken(jid));
-        if (entry && entry.token && entry.token.length) {
-          children = [new BinaryNode('privacy', {}, entry.token)];
-        }
+        const token = this._tcTokenFor(jid);
+        if (token) children = [new BinaryNode('privacy', {}, token)];
       }
       return new BinaryNode('participant', attrs, children);
     });