whalibmob 5.5.93 → 5.6.2

package/lib/WebStore.js

@@ -0,0 +1,117 @@
+'use strict';
+
+// Session state for a WhatsApp Web (companion) link.
+//
+// Deliberately the same shape as the mobile store: SignalProtocol,
+// DeviceManager and MessageSender all read `noiseKeyPair`, `identityKeyPair`,
+// `signedPreKey`, `registrationId` and `advIdentity` off it, and none of them
+// should have to care which way the session was established. What web mode adds
+// on top is the pairing material and the identity the server hands back:
+//
+//   advSecretKey            derived during pairing; every later proof that this
+//                           device belongs to the account is an HMAC under it
+//   pairingEphemeralKeyPair one half of the code-authenticated exchange
+//   pairingCode             the eight characters shown to the human
+//   me                      { id, lid, name } — the JID we were issued
+//   deviceIndex             which linked-device slot we occupy; 0 is the phone
+//
+// Stored beside the mobile session as `<phone>.web.json`, so registering a
+// number over SMS and linking it as a companion never overwrite each other.
+
+const fs      = require('fs');
+const path    = require('path');
+const crypto  = require('crypto');
+
+const { createNewStore, storeToJson, storeFromJson } = require('./Store');
+const { WEB_VERSION_FALLBACK, WEB_BROWSER } = require('./constants');
+const { generateEphemeralKeyPair } = require('./PairingCode');
+
+function webSessionPath(sessionDir, phoneNumber) {
+  return path.join(sessionDir, `${String(phoneNumber).replace(/\D/g, '')}.web.json`);
+}
+
+function createNewWebStore(phoneNumber) {
+  const store = createNewStore(phoneNumber);
+
+  store.mode                    = 'web';
+  store.registered              = false;
+  store.advSecretKey            = null;
+  store.pairingCode             = null;
+  store.pairingEphemeralKeyPair = generateEphemeralKeyPair();
+  store.me                      = null;
+  store.deviceIndex             = 0;
+  store.platform                = null;
+  store.webVersion              = WEB_VERSION_FALLBACK.slice();
+  store.browser                 = WEB_BROWSER.slice();
+  store.syncFullHistory         = true;
+
+  return store;
+}
+
+function webStoreToJson(store) {
+  const base = storeToJson(store);
+  return Object.assign(base, {
+    mode:        'web',
+    advSecretKey: store.advSecretKey || null,
+    pairingCode:  store.pairingCode  || null,
+    pairingEphemeralKeyPair: store.pairingEphemeralKeyPair ? {
+      private: store.pairingEphemeralKeyPair.private.toString('base64'),
+      public:  store.pairingEphemeralKeyPair.public.toString('base64')
+    } : null,
+    me:          store.me          || null,
+    deviceIndex: store.deviceIndex || 0,
+    platform:    store.platform    || null,
+    webVersion:  store.webVersion  || WEB_VERSION_FALLBACK.slice(),
+    browser:     store.browser     || WEB_BROWSER.slice(),
+    syncFullHistory: store.syncFullHistory !== false
+  });
+}
+
+function webStoreFromJson(obj) {
+  const store = storeFromJson(obj);
+
+  store.mode         = 'web';
+  store.advSecretKey = obj.advSecretKey || null;
+  store.pairingCode  = obj.pairingCode  || null;
+  store.pairingEphemeralKeyPair = obj.pairingEphemeralKeyPair
+    ? {
+        private: Buffer.from(obj.pairingEphemeralKeyPair.private, 'base64'),
+        public:  Buffer.from(obj.pairingEphemeralKeyPair.public, 'base64')
+      }
+    // A store written before this field existed still needs a usable key pair;
+    // it is only ever consumed inside a single pairing attempt.
+    : generateEphemeralKeyPair();
+  store.me          = obj.me          || null;
+  store.deviceIndex = obj.deviceIndex || 0;
+  store.platform    = obj.platform    || null;
+  store.webVersion  = obj.webVersion  || WEB_VERSION_FALLBACK.slice();
+  store.browser     = obj.browser     || WEB_BROWSER.slice();
+  store.syncFullHistory = obj.syncFullHistory !== false;
+
+  return store;
+}
+
+function saveWebStore(store, filePath) {
+  if (!store) return;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(webStoreToJson(store), null, 2), 'utf8');
+}
+
+function loadWebStore(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return webStoreFromJson(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = {
+  createNewWebStore,
+  saveWebStore,
+  loadWebStore,
+  webStoreToJson,
+  webStoreFromJson,
+  webSessionPath
+};

package/lib/constants.js

@@ -7,6 +7,26 @@ const REGISTRATION_PUBLIC_KEY = Buffer.from('8e8c0f74c3ebc5d7a6865c6c3c843856b06
 
 const MOBILE_PROLOGUE = Buffer.from([0x57, 0x41, 0x05, 0x03]);
 
+// ─── WhatsApp Web (companion) transport ──────────────────────────────────────
+//
+// The mobile client speaks the same Noise handshake and the same binary node
+// dictionary over a raw TLS socket to g.whatsapp.net. The web client speaks it
+// over a WebSocket to web.whatsapp.com. The only wire-level differences are the
+// prologue byte that announces which edition is talking (5 = mobile,
+// 6 = web/multi-device) and the ClientPayload that rides inside the handshake.
+const WEB_PROLOGUE   = Buffer.from([0x57, 0x41, 0x06, 0x03]);
+const WEB_SOCKET_URL = 'wss://web.whatsapp.com/ws/chat';
+const WEB_ORIGIN     = 'https://web.whatsapp.com';
+
+// Version the companion announces. Unlike the mobile version this is not tied
+// to an App Store build — it is the web client release, and the server is
+// tolerant of a slightly stale one.
+const WEB_VERSION_FALLBACK = [2, 3000, 1027934701];
+
+// [os, browser] pair. Decides the DeviceProps.platformType we register with and
+// the name the account owner sees in the linked-devices list on their phone.
+const WEB_BROWSER = ['Ubuntu', 'Chrome', '120.0.0.0'];
+
 // Static tokens used in WhatsApp registration token computation.
 // token = MD5( staticToken + MD5hex(waVersion) + nationalNumber )
 const IOS_STATIC_TOKEN          = '0a1mLfGUIBVrMKF1RdvLI5lkRBvof6vn0fD2QRSM';
@@ -197,6 +217,11 @@ module.exports = {
   REGISTRATION_ENDPOINT,
   REGISTRATION_PUBLIC_KEY,
   MOBILE_PROLOGUE,
+  WEB_PROLOGUE,
+  WEB_SOCKET_URL,
+  WEB_ORIGIN,
+  WEB_VERSION_FALLBACK,
+  WEB_BROWSER,
   IOS_STATIC_TOKEN,
   IOS_BUSINESS_STATIC_TOKEN,
   ANDROID_STATIC_TOKEN,

package/lib/messages/MessageSender.js

@@ -933,15 +933,19 @@ class MessageSender {
       ]);
       otherJids     = lidDevices.length > 0 ? lidDevices : [toJid];
       ownLinkedJids = ownLidDevices;
-      ownPrimaryJid = `${ownLidUser}@lid`;
+      ownPrimaryJid = this._client._ownDeviceLidJid() || `${ownLidUser}@lid`;
     } else {
       const [pnDevices, ownDevices] = await Promise.all([
         this._devMgr.bulkEnsureSessions([recipientPhone], this._signal, allowPkmsg),
         this._devMgr.ensureOwnDeviceSessions(ownPhone, this._signal, allowPkmsg)
       ]);
       otherJids     = pnDevices.length > 0 ? pnDevices : [toJid];
-      ownLinkedJids = ownDevices.filter(j => j !== ownMainJid);
-      ownPrimaryJid = ownMainJid;
+      // Every own device except the one doing the sending. As a primary that is
+      // device 0 and the list below drops it; as a companion the account's
+      // phone is device 0 and must stay in — it is a peer we encrypt to, not
+      // ourselves. The filter a few lines down removes whichever one we are.
+      ownLinkedJids = ownDevices;
+      ownPrimaryJid = this._client._ownDeviceJid();
     }
 
     // The device doing the sending is never one of its own recipients. Both
@@ -1193,7 +1197,13 @@ class MessageSender {
     // For LID-mode groups, sender identity is own LID JID; otherwise own PN JID.
     // Normalised to the bare user so it matches the participant targets below.
     const selfJid = useLid ? `${myLidUser}@lid` : ownJid;
-    const senderIdentity = selfJid;
+    // The SenderKey is this device's, so the identity it is filed under carries
+    // our device index. On a primary that index is 0 and this is exactly the
+    // bare JID above; on a companion it keeps our key distinct from the
+    // account's phone, which distributes its own.
+    const senderIdentity = (useLid
+      ? this._client._ownDeviceLidJid()
+      : this._client._ownDeviceJid()) || selfJid;
 
     const rawSKDM   = await this._signal.buildSKDM(groupJid, senderIdentity);
     const skdmMsg   = encodeSenderKeyDistributionMessage(groupJid, rawSKDM);
@@ -1277,8 +1287,14 @@ class MessageSender {
 
     // Targets to actually encrypt for: everything but the sending device. Both
     // Baileys and whatsmeow skip it explicitly at this point and not before.
-    const selfAddrs = new Set([adString(`${ownPhone}@s.whatsapp.net`)]);
-    if (myLidUser) selfAddrs.add(adString(`${myLidUser}@lid`));
+    // Only the device actually sending. On a companion link that is not the
+    // account's phone — the phone is a peer that has to receive the SenderKey
+    // like everyone else, so excluding the bare number here would leave the
+    // owner's own phone unable to read the message.
+    const selfAddrs = new Set([adString(this._client._ownDeviceJid())]);
+    const ownLidSelf = this._client._ownDeviceLidJid();
+    if (ownLidSelf)     selfAddrs.add(adString(ownLidSelf));
+    else if (myLidUser) selfAddrs.add(adString(`${myLidUser}@lid`));
     const allTargets = enumeratedDevices.filter(jid => !selfAddrs.has(adString(jid)));
 
     // Whatever the member list said, if nothing came back with a session there
@@ -1651,7 +1667,10 @@ class MessageSender {
       await this._fetchMediaConn();
       return { hosts: this._mediaHosts, auth: this._mediaAuth };
     };
-    return uploadMedia(mediaType, buf, this._mediaHosts, this._mediaAuth, refreshAuth);
+    // A companion talks to the CDN as a browser: different endpoint for the
+    // types the web client folds together, and an Origin header.
+    return uploadMedia(mediaType, buf, this._mediaHosts, this._mediaAuth, refreshAuth,
+      { web: this._client && this._client._mode === 'web' });
   }
 
   async _fetchMediaConn() {

package/lib/noise.js

@@ -6,7 +6,7 @@ const EventEmitter = require('events');
 const curveJs      = require('curve25519-js');
 const { sha256 }   = require('@noble/hashes/sha256');
 const { hkdf }     = require('@noble/hashes/hkdf');
-const { MOBILE_PROLOGUE, WHATSAPP_HOST, WHATSAPP_PORT } = require('./constants');
+const { MOBILE_PROLOGUE, WEB_PROLOGUE, WHATSAPP_HOST, WHATSAPP_PORT } = require('./constants');
 const { encodeHandshakeClientHello, encodeHandshakeClientFinish,
         decodeServerHello, encodeClientPayload } = require('./proto');
 const { parsePhone, getCountryMeta } = require('./Registration');
@@ -112,7 +112,10 @@ function deriveHkdf(salt, ikm, length) {
 }
 
 class NoiseState {
-  constructor() {
+  // The prologue is mixed into the handshake hash, so mobile and web produce
+  // different transcripts from the first byte and a payload built for one
+  // edition can never authenticate against the other.
+  constructor(prologue) {
     // Noise spec: if protocol_name.length <= HASHLEN(32), h = protocol_name padded with zeros.
     // Do NOT hash — use the raw 32-byte name directly as the initial h and ck.
     const modeBytes = Buffer.from(NOISE_MODE, 'utf8'); // 'Noise_XX_25519_AESGCM_SHA256\0\0\0\0' = 32 bytes
@@ -120,7 +123,7 @@ class NoiseState {
     this.ck      = Buffer.from(modeBytes);
     this.key     = null;  // single key for both enc+dec during handshake
     this.counter = 0;     // single counter for both encrypt+decrypt
-    this.hash(MOBILE_PROLOGUE);
+    this.hash(prologue || MOBILE_PROLOGUE);
   }
 
   hash(data) {
@@ -188,8 +191,26 @@ function readFrameLength(data) {
 //   'error'(err)  — an error occurred
 //
 class NoiseSocket extends EventEmitter {
-  constructor(store) {
+  /**
+   * @param {object} store   session store
+   * @param {object} [opts]
+   *   transport      'mobile' (raw TLS to g.whatsapp.net) or 'web' (WebSocket
+   *                  to web.whatsapp.com). Defaults to mobile — every existing
+   *                  caller keeps its behaviour without passing anything.
+   *   buildPayload   () => Buffer, replaces the mobile ClientPayload. Web mode
+   *                  supplies the companion register/login payload here.
+   *   expectSuccess  when false the connect() promise resolves as soon as the
+   *                  channel is secured instead of waiting for <success>. A
+   *                  companion that has not been paired yet never receives one:
+   *                  the server replies with pair-device and waits for a human.
+   */
+  constructor(store, opts) {
     super();
+    opts = opts || {};
+    this.transport     = opts.transport === 'web' ? 'web' : 'mobile';
+    this._buildPayload = opts.buildPayload || null;
+    this._expectSuccess = opts.expectSuccess !== false;
+    this._prologue     = this.transport === 'web' ? WEB_PROLOGUE : MOBILE_PROLOGUE;
     this.store        = store;
     this.socket       = null;
     this.noiseState   = null;
@@ -211,7 +232,12 @@ class NoiseSocket extends EventEmitter {
       this._connectResolve = resolve;
       this._connectReject  = reject;
 
-      this.socket = net.createConnection({ host: WHATSAPP_HOST, port: WHATSAPP_PORT });
+      if (this.transport === 'web') {
+        const { WebSocketStream } = require('./WebSocketStream');
+        this.socket = new WebSocketStream().connect();
+      } else {
+        this.socket = net.createConnection({ host: WHATSAPP_HOST, port: WHATSAPP_PORT });
+      }
       // OS-level TCP keepalive: detects silently-dead NAT connections that never send FIN/RST
       this.socket.setKeepAlive(true, 15000);
       // Connect-phase watchdog: abort if TCP handshake takes >20s
@@ -241,7 +267,7 @@ class NoiseSocket extends EventEmitter {
   }
 
   _startHandshake() {
-    this.noiseState    = new NoiseState();
+    this.noiseState    = new NoiseState(this._prologue);
     const seed         = crypto.randomBytes(32);
     const kp           = curveJs.generateKeyPair(seed);
     this._ephemeralKeyPair = {
@@ -251,7 +277,7 @@ class NoiseSocket extends EventEmitter {
     this.noiseState.hash(this._ephemeralKeyPair.public);
 
     const helloPayload = encodeHandshakeClientHello(this._ephemeralKeyPair.public);
-    const frame        = Buffer.concat([MOBILE_PROLOGUE, makeFrame(helloPayload)]);
+    const frame        = Buffer.concat([this._prologue, makeFrame(helloPayload)]);
     this.socket.write(frame);
   }
 
@@ -302,6 +328,37 @@ class NoiseSocket extends EventEmitter {
       const sharedSS   = dhShared(noisePriv, serverHello.ephemeral);
       this.noiseState.mixKey(sharedSS);
 
+      // Web mode hands us a finished companion payload; there is no phone
+      // identity to derive anything from, and the fields below do not exist on
+      // that side of the protocol.
+      if (this._buildPayload) {
+        const encPayload = this.noiseState.encryptWithAd(this._buildPayload());
+        const finish     = encodeHandshakeClientFinish(encStatic, encPayload);
+        this.socket.write(makeFrame(finish));
+
+        const webKeys     = this.noiseState.split();
+        this.writeKey     = webKeys.writeKey;
+        this.readKey      = webKeys.readKey;
+        this.writeCounter = 0;
+        this.readCounter  = 0;
+        this.secured      = true;
+
+        if (this._expectSuccess) {
+          this._awaitingAuth = true;
+        } else {
+          // An unpaired companion gets pair-device, not <success>. Hand the
+          // caller a live channel and let the pairing flow drive from here.
+          this._awaitingAuth = false;
+          if (this._connectResolve) {
+            this._connectResolve();
+            this._connectResolve = null;
+            this._connectReject  = null;
+          }
+          this.emit('secured');
+        }
+        return;
+      }
+
       // Auto-derive MCC/MNC and locale from the registered phone number so the
       // ClientPayload userAgent is never sent with the telltale '000'/'000' values.
       const _phoneMeta  = getCountryMeta(parsePhone(this.store.phoneNumber).cc);
@@ -411,6 +468,14 @@ class NoiseSocket extends EventEmitter {
       }
       // ─────────────────────────────────────────────────────────────────────
 
+      // A companion that connected unpaired resolves connect() early, so
+      // <success> arrives here as an ordinary node once the link completes.
+      // It still means the same thing, so it still opens the session.
+      if (!this._expectSuccess && node && node.description === 'success') {
+        this.emit('open', node);
+        return;
+      }
+
       this.emit('node', node);
     } catch (err) {
       this.emit('error', err);

package/lib/signal/SignalProtocol.js

@@ -282,11 +282,20 @@ class SignalProtocol {
   // SenderKeyName format: groupId::senderId::0 (device 0 for group identity).
 
   _senderKeyName(groupId, senderId) {
-    // Strip device suffix (e.g. "1234567890:2@lid" → "1234567890")
-    const user = typeof senderId === 'string'
-      ? senderId.split('@')[0].split(':')[0]
-      : String(senderId);
-    return new SenderKeyName(groupId, { id: user, deviceId: 0 });
+    // A SenderKey belongs to a device, not to an account. Every device that
+    // posts to a group distributes its own key, so the name has to carry the
+    // device index the way Baileys and whatsmeow do — otherwise two devices of
+    // the same person share one slot and the second one to speak overwrites
+    // the first, leaving its messages undecryptable.
+    //
+    // Bare JIDs still resolve to device 0, so everything already on disk keeps
+    // the exact same key string.
+    const raw     = typeof senderId === 'string' ? senderId : String(senderId);
+    const userPart = raw.split('@')[0];
+    const colon    = userPart.indexOf(':');
+    const user     = colon >= 0 ? userPart.slice(0, colon) : userPart;
+    const deviceId = colon >= 0 ? (parseInt(userPart.slice(colon + 1), 10) || 0) : 0;
+    return new SenderKeyName(groupId, { id: user, deviceId });
   }
 
   async senderKeyEncrypt(groupId, senderId, plaintext) {

package/lib/webproto.js

@@ -0,0 +1,273 @@
+'use strict';
+
+// ClientPayload encoders for the WhatsApp Web (companion) handshake.
+//
+// The mobile handshake in proto.js builds a payload around `username` and a
+// phone-shaped UserAgent. A companion sends the same message type with a
+// different set of fields: on its very first connection it carries
+// devicePairingData — the registration bundle the account's primary device
+// signs during pairing — and on every connection after that it carries the
+// device index the server issued and asks to be caught up.
+//
+// Written by hand against the wire format for the same reason proto.js is:
+// keeping the handshake independent of a protobuf runtime.
+
+const crypto = require('crypto');
+
+// ─── primitives ──────────────────────────────────────────────────────────────
+
+function encodeVarint(n) {
+  const out = [];
+  let v = n >>> 0;
+  do {
+    let b = v & 0x7f;
+    v >>>= 7;
+    if (v) b |= 0x80;
+    out.push(b);
+  } while (v);
+  return Buffer.from(out);
+}
+
+// username is a uint64 — the 32-bit helper above truncates long international
+// numbers, so it gets its own encoder.
+function encodeVarint64(value) {
+  const out = [];
+  let v = BigInt(value);
+  do {
+    let b = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v > 0n) b |= 0x80;
+    out.push(b);
+  } while (v > 0n);
+  return Buffer.from(out);
+}
+
+function field(num, wireType, valueBytes) {
+  return Buffer.concat([encodeVarint((num << 3) | wireType), valueBytes]);
+}
+
+function bytesField(num, buf)  { return field(num, 2, Buffer.concat([encodeVarint(buf.length), buf])); }
+function stringField(num, str) { return bytesField(num, Buffer.from(String(str), 'utf8')); }
+function varintField(num, n)   { return field(num, 0, encodeVarint(n)); }
+function uint64Field(num, n)   { return field(num, 0, encodeVarint64(n)); }
+function boolField(num, v)     { return varintField(num, v ? 1 : 0); }
+
+// WhatsApp encodes registration ids and pre-key ids inside the pairing bundle
+// as fixed-width big-endian byte strings, not as varints.
+function encodeBigEndian(value, length) {
+  length = length || 4;
+  const buf = Buffer.alloc(length);
+  for (let i = length - 1; i >= 0; i--) {
+    buf[i] = value & 0xff;
+    value = Math.floor(value / 256);
+  }
+  return buf;
+}
+
+function stripKeyPrefix(pub) {
+  if (pub && pub.length === 33 && pub[0] === 0x05) return pub.slice(1);
+  return pub;
+}
+
+// ─── DeviceProps ─────────────────────────────────────────────────────────────
+//
+// How the companion describes itself to the primary. `os` and the platform type
+// are what the account owner reads in the linked-devices list on their phone;
+// historySyncConfig decides how much of the past the primary ships over once
+// the link is established.
+
+const PLATFORM_TYPE = {
+  UNKNOWN: 0, CHROME: 1, FIREFOX: 2, IE: 3, OPERA: 4, SAFARI: 5, EDGE: 6,
+  DESKTOP: 7, IPAD: 8, ANDROID_TABLET: 9, OHANA: 10, ALOHA: 11, CATALINA: 12,
+  TCL_TV: 13, IOS_PHONE: 14, IOS_CATALYST: 15, ANDROID_PHONE: 16,
+  ANDROID_AMBIGUOUS: 17, WEAR_OS: 18, AR_WRIST: 19, AR_DEVICE: 20, UWP: 21,
+  VR: 22, CLOUD_API: 23, SMARTGLASSES: 24
+};
+
+function platformTypeFor(browserName) {
+  const key = String(browserName || '').toUpperCase();
+  if (key === 'ANDROID') return PLATFORM_TYPE.ANDROID_PHONE;
+  return PLATFORM_TYPE[key] !== undefined ? PLATFORM_TYPE[key] : PLATFORM_TYPE.CHROME;
+}
+
+// DeviceProps.HistorySyncConfig
+function encodeHistorySyncConfig(opts) {
+  opts = opts || {};
+  const parts = [
+    varintField(3, opts.storageQuotaMb != null ? opts.storageQuotaMb : 10240),
+    boolField(4, opts.inlineInitialPayloadInE2EeMsg !== false),
+    boolField(6, !!opts.supportCallLogHistory),
+    boolField(7, opts.supportBotUserAgentChatHistory !== false),
+    boolField(8, opts.supportCagReactionsAndPolls !== false),
+    boolField(9, opts.supportBizHostedMsg !== false),
+    boolField(10, opts.supportRecentSyncChunkMessageCountTuning !== false),
+    boolField(11, opts.supportHostedGroupMsg !== false),
+    boolField(12, opts.supportFbidBotChatHistory !== false),
+    boolField(14, opts.supportMessageAssociation !== false),
+    boolField(15, !!opts.supportGroupHistory)
+  ];
+  if (opts.fullSyncDaysLimit)  parts.unshift(varintField(1, opts.fullSyncDaysLimit));
+  if (opts.fullSyncSizeMbLimit) parts.unshift(varintField(2, opts.fullSyncSizeMbLimit));
+  return Buffer.concat(parts);
+}
+
+// DeviceProps.AppVersion — the companion's own version, not the account's.
+function encodeDevicePropsVersion(primary, secondary, tertiary) {
+  return Buffer.concat([
+    varintField(1, primary),
+    varintField(2, secondary),
+    varintField(3, tertiary)
+  ]);
+}
+
+function encodeDeviceProps(opts) {
+  opts = opts || {};
+  return Buffer.concat([
+    stringField(1, opts.os || 'Ubuntu'),
+    bytesField(2, encodeDevicePropsVersion(10, 15, 7)),
+    varintField(3, platformTypeFor(opts.browserName || 'Chrome')),
+    boolField(4, !!opts.requireFullSync),
+    bytesField(5, encodeHistorySyncConfig(opts.historySync))
+  ]);
+}
+
+// ─── ClientPayload.UserAgent ─────────────────────────────────────────────────
+//
+// Platform 14 = WEB. Carries no phone identifiers at all — no real mcc/mnc, no
+// device id, no phone id. That absence is part of what marks the connection as
+// a companion rather than a primary.
+
+const PLATFORM_WEB     = 14;
+const PLATFORM_ANDROID = 0;
+
+function encodeAppVersion(v) {
+  return Buffer.concat([
+    varintField(1, v[0]),
+    varintField(2, v[1]),
+    varintField(3, v[2])
+  ]);
+}
+
+function encodeWebUserAgent(opts) {
+  const version = opts.version || [2, 3000, 1];
+  const browser = opts.browser || ['Ubuntu', 'Chrome', '120.0.0.0'];
+  const isAndroid = String(browser[1] || '').toLowerCase().includes('android');
+  return Buffer.concat([
+    varintField(1, isAndroid ? PLATFORM_ANDROID : PLATFORM_WEB),
+    bytesField(2, encodeAppVersion(version)),
+    stringField(3, '000'),                                  // mcc
+    stringField(4, '000'),                                  // mnc
+    stringField(5, '0.1'),                                  // osVersion
+    stringField(6, 'Desktop'),                              // manufacturer
+    stringField(7, 'Desktop'),                              // device
+    stringField(8, '0.1'),                                  // osBuildNumber
+    varintField(10, 0),                                     // releaseChannel = RELEASE
+    stringField(11, 'en'),                                  // localeLanguageIso6391
+    stringField(12, String(opts.countryCode || 'US'))       // localeCountryIso31661Alpha2
+  ]);
+}
+
+// ClientPayload.WebInfo — webSubPlatform (field 4), WEB_BROWSER = 0.
+function encodeWebInfo() {
+  return varintField(4, 0);
+}
+
+// ─── ClientPayload.DevicePairingRegistrationData ─────────────────────────────
+//
+// The bundle the primary device signs. eIdent is our identity public key, and
+// the account signature returned in pair-success is made over it — that is the
+// link between this companion and the account.
+function encodeDevicePairingData(o) {
+  return Buffer.concat([
+    bytesField(1, o.eRegid),
+    bytesField(2, o.eKeytype),
+    bytesField(3, o.eIdent),
+    bytesField(4, o.eSkeyId),
+    bytesField(5, o.eSkeyVal),
+    bytesField(6, o.eSkeySig),
+    bytesField(7, o.buildHash),
+    bytesField(8, o.deviceProps)
+  ]);
+}
+
+// ─── ClientPayload ───────────────────────────────────────────────────────────
+//
+// Field numbers, straight off the schema:
+//   1 username · 3 passive · 5 userAgent · 6 webInfo · 7 pushName
+//   12 connectType · 13 connectReason · 18 device · 19 devicePairingData
+//   33 pull
+
+const CONNECT_TYPE_WIFI_UNKNOWN     = 1;
+const CONNECT_REASON_USER_ACTIVATED = 1;
+
+function commonWebPayload(opts) {
+  const parts = [
+    bytesField(5, encodeWebUserAgent(opts)),
+    bytesField(6, encodeWebInfo()),
+    varintField(12, CONNECT_TYPE_WIFI_UNKNOWN),
+    varintField(13, CONNECT_REASON_USER_ACTIVATED)
+  ];
+  if (opts.pushName) parts.push(stringField(7, opts.pushName));
+  return parts;
+}
+
+/**
+ * First connection of a brand-new companion. There is no JID yet, so the
+ * payload carries the pairing bundle; the server answers with a pair-device
+ * (the QR path) or, once a pairing code has been requested and typed into the
+ * phone, with a pair-success.
+ */
+function encodeCompanionRegisterPayload(opts) {
+  const version   = opts.version || [2, 3000, 1];
+  const buildHash = crypto.createHash('md5').update(version.join('.')).digest();
+
+  const deviceProps = encodeDeviceProps({
+    os:              (opts.browser && opts.browser[0]) || 'Ubuntu',
+    browserName:     (opts.browser && opts.browser[1]) || 'Chrome',
+    requireFullSync: !!opts.syncFullHistory,
+    historySync:     opts.historySync
+  });
+
+  const pairing = encodeDevicePairingData({
+    buildHash,
+    deviceProps,
+    eRegid:   encodeBigEndian(opts.registrationId, 4),
+    eKeytype: Buffer.from([5]),
+    eIdent:   stripKeyPrefix(opts.identityKeyPair.public),
+    eSkeyId:  encodeBigEndian(opts.signedPreKey.id, 3),
+    eSkeyVal: stripKeyPrefix(opts.signedPreKey.public),
+    eSkeySig: opts.signedPreKey.signature
+  });
+
+  return Buffer.concat([
+    ...commonWebPayload(opts),
+    boolField(3, false),            // passive
+    boolField(33, false),           // pull
+    bytesField(19, pairing)         // devicePairingData
+  ]);
+}
+
+/**
+ * Every connection after pairing. `username` is the account's phone number and
+ * `device` is the index the server assigned us; together they form the JID the
+ * primary lists under Linked Devices.
+ */
+function encodeCompanionLoginPayload(opts) {
+  return Buffer.concat([
+    uint64Field(1, opts.username),
+    ...commonWebPayload(opts),
+    boolField(3, true),             // passive
+    boolField(33, true),            // pull
+    varintField(18, opts.device || 0)
+  ]);
+}
+
+module.exports = {
+  encodeCompanionRegisterPayload,
+  encodeCompanionLoginPayload,
+  encodeDeviceProps,
+  encodeHistorySyncConfig,
+  encodeBigEndian,
+  platformTypeFor,
+  PLATFORM_TYPE
+};