whalibmob 5.5.93 → 5.6.2

package/lib/CompanionPairing.js

@@ -0,0 +1,247 @@
+'use strict';
+
+// pair-success: the moment a companion becomes part of the account.
+//
+// The primary device sends back an ADVSignedDeviceIdentity — a small record
+// saying "this identity key is mine, at this key index, from this timestamp" —
+// wrapped in an HMAC under adv_secret, the key both sides derived during the
+// pairing exchange. Three checks have to pass before we accept it:
+//
+//   1. the HMAC, which proves it came from someone holding adv_secret;
+//   2. the account signature over our own identity public key, which proves the
+//      primary really did authorise *this* device and not some other one;
+//   3. nothing about our own key material has changed underneath us.
+//
+// Then we counter-sign with our identity key and hand it back. That signed
+// record is what rides on every pkmsg we send from then on: it is how the
+// recipient's client knows a message from device 7 of an account is genuinely
+// from that account.
+
+const crypto  = require('crypto');
+const curveJs = require('curve25519-js');
+
+const WA_ADV_ACCOUNT_SIG_PREFIX        = Buffer.from([6, 0]);
+const WA_ADV_DEVICE_SIG_PREFIX         = Buffer.from([6, 1]);
+const WA_ADV_HOSTED_ACCOUNT_SIG_PREFIX = Buffer.from([6, 5]);
+
+const ADV_ENCRYPTION_TYPE_HOSTED = 1;
+
+// ─── minimal protobuf reader ─────────────────────────────────────────────────
+//
+// Same approach the rest of the library takes: these messages are four fields
+// wide and never change, so a reader is cheaper than a schema runtime.
+
+function readVarint(buf, off) {
+  let v = 0, shift = 0;
+  while (off.pos < buf.length) {
+    const b = buf[off.pos++];
+    v += (b & 0x7f) * Math.pow(2, shift);
+    if (!(b & 0x80)) break;
+    shift += 7;
+  }
+  return v;
+}
+
+function readFields(buf) {
+  const fields = {};
+  const off = { pos: 0 };
+  while (off.pos < buf.length) {
+    const tag = readVarint(buf, off);
+    const fieldNum = tag >>> 3;
+    const wireType = tag & 7;
+    if (wireType === 0) {
+      fields[fieldNum] = readVarint(buf, off);
+    } else if (wireType === 2) {
+      const len = readVarint(buf, off);
+      fields[fieldNum] = buf.slice(off.pos, off.pos + len);
+      off.pos += len;
+    } else if (wireType === 5) {
+      fields[fieldNum] = buf.slice(off.pos, off.pos + 4);
+      off.pos += 4;
+    } else if (wireType === 1) {
+      fields[fieldNum] = buf.slice(off.pos, off.pos + 8);
+      off.pos += 8;
+    } else {
+      break;
+    }
+  }
+  return fields;
+}
+
+function varint(n) {
+  const out = [];
+  let v = n;
+  do {
+    let b = v & 0x7f;
+    v = Math.floor(v / 128);
+    if (v) b |= 0x80;
+    out.push(b);
+  } while (v);
+  return Buffer.from(out);
+}
+
+function bytesField(num, buf) {
+  return Buffer.concat([varint((num << 3) | 2), varint(buf.length), buf]);
+}
+
+/**
+ * Re-encode an ADVSignedDeviceIdentity, optionally without the account
+ * signature key.
+ *
+ * The reply we send back omits it — the primary already has its own key and
+ * echoing it adds nothing — while the copy we keep for pkmsg attachment keeps
+ * it, because recipients need it to verify our device signature.
+ */
+function encodeSignedDeviceIdentity(account, includeSignatureKey) {
+  const parts = [bytesField(1, account.details)];
+  if (includeSignatureKey && account.accountSignatureKey && account.accountSignatureKey.length) {
+    parts.push(bytesField(2, account.accountSignatureKey));
+  }
+  if (account.accountSignature) parts.push(bytesField(3, account.accountSignature));
+  if (account.deviceSignature)  parts.push(bytesField(4, account.deviceSignature));
+  return Buffer.concat(parts);
+}
+
+function stripKeyPrefix(pub) {
+  if (pub && pub.length === 33 && pub[0] === 0x05) return pub.slice(1);
+  return pub;
+}
+
+function findChild(node, desc) {
+  if (!node || !Array.isArray(node.content)) return null;
+  return node.content.find(c => c && c.description === desc) || null;
+}
+
+function jidToString(v) {
+  if (v == null) return null;
+  if (typeof v === 'string') return v;
+  // BinaryNode decodes JIDs into { user, device, server }
+  const user   = v.user != null ? String(v.user) : '';
+  const server = v.server || 's.whatsapp.net';
+  const device = v.device ? ':' + v.device : '';
+  return user + device + '@' + server;
+}
+
+/**
+ * Validate a <pair-success> stanza and build the reply.
+ *
+ * @param {object} stanza        the full <iq> containing <pair-success>
+ * @param {object} creds         { advSecretKey, identityKeyPair }
+ * @returns {{reply: object, me: object, account: object, accountEnc: Buffer,
+ *            platform: string|null, deviceIndex: number, keyIndex: number}}
+ */
+function configureSuccessfulPairing(stanza, creds, BinaryNode) {
+  const msgId = stanza.attrs && stanza.attrs.id;
+
+  const pairSuccess = findChild(stanza, 'pair-success');
+  if (!pairSuccess) throw new Error('pair-success: node missing from stanza');
+
+  const deviceIdentityNode = findChild(pairSuccess, 'device-identity');
+  const platformNode       = findChild(pairSuccess, 'platform');
+  const deviceNode         = findChild(pairSuccess, 'device');
+  const businessNode       = findChild(pairSuccess, 'biz');
+
+  if (!deviceIdentityNode || !deviceNode) {
+    throw new Error('pair-success: missing device-identity or device');
+  }
+
+  const hmacMsg = readFields(Buffer.from(deviceIdentityNode.content));
+  const details = hmacMsg[1];
+  const hmac    = hmacMsg[2];
+  const accountType = hmacMsg[3];
+  if (!details || !hmac) throw new Error('pair-success: malformed ADVSignedDeviceIdentityHMAC');
+
+  // 1. HMAC — proves the record came from a holder of adv_secret.
+  const hmacPrefix = accountType === ADV_ENCRYPTION_TYPE_HOSTED
+    ? WA_ADV_HOSTED_ACCOUNT_SIG_PREFIX
+    : Buffer.alloc(0);
+  const advSign = crypto.createHmac('sha256', Buffer.from(creds.advSecretKey, 'base64'))
+    .update(Buffer.concat([hmacPrefix, details]))
+    .digest();
+  if (Buffer.compare(hmac, advSign) !== 0) {
+    throw new Error('pair-success: invalid account signature HMAC — pairing code mismatch');
+  }
+
+  const account = readFields(details);
+  const accountSignatureKey = account[2];
+  const accountSignature    = account[3];
+  const deviceDetails       = account[1];
+  if (!accountSignatureKey || !accountSignature || !deviceDetails) {
+    throw new Error('pair-success: malformed ADVSignedDeviceIdentity');
+  }
+
+  const deviceIdentity = readFields(deviceDetails);
+  const keyIndex   = deviceIdentity[3] || 0;
+  const deviceType = deviceIdentity[5];
+
+  // 2. Account signature over our identity key — proves the primary authorised
+  //    this exact device.
+  const ourIdentityPub = stripKeyPrefix(creds.identityKeyPair.public);
+  const accountSigPrefix = deviceType === ADV_ENCRYPTION_TYPE_HOSTED
+    ? WA_ADV_HOSTED_ACCOUNT_SIG_PREFIX
+    : WA_ADV_ACCOUNT_SIG_PREFIX;
+  const accountMsg = Buffer.concat([accountSigPrefix, deviceDetails, ourIdentityPub]);
+  if (!curveJs.verify(stripKeyPrefix(accountSignatureKey), accountMsg, accountSignature)) {
+    throw new Error('pair-success: failed to verify account signature');
+  }
+
+  // 3. Counter-sign. This is the signature recipients check on our pkmsgs.
+  const deviceMsg = Buffer.concat([
+    WA_ADV_DEVICE_SIG_PREFIX,
+    deviceDetails,
+    ourIdentityPub,
+    stripKeyPrefix(accountSignatureKey)
+  ]);
+  const deviceSignature = Buffer.from(
+    curveJs.sign(creds.identityKeyPair.private, deviceMsg)
+  );
+
+  const signedAccount = {
+    details:             deviceDetails,
+    accountSignatureKey: stripKeyPrefix(accountSignatureKey),
+    accountSignature,
+    deviceSignature
+  };
+
+  const jid = jidToString(deviceNode.attrs && deviceNode.attrs.jid);
+  const lid = jidToString(deviceNode.attrs && deviceNode.attrs.lid);
+  const deviceIndex = jid && jid.includes(':')
+    ? parseInt(jid.split('@')[0].split(':')[1], 10) || 0
+    : 0;
+
+  const reply = new BinaryNode('iq', {
+    to:   's.whatsapp.net',
+    type: 'result',
+    id:   msgId
+  }, [
+    new BinaryNode('pair-device-sign', {}, [
+      new BinaryNode('device-identity', { 'key-index': String(keyIndex) },
+        encodeSignedDeviceIdentity(signedAccount, false))
+    ])
+  ]);
+
+  return {
+    reply,
+    me: {
+      id:   jid,
+      lid:  lid,
+      name: (businessNode && businessNode.attrs && businessNode.attrs.name) || null
+    },
+    account:    signedAccount,
+    // What gets persisted and attached to outgoing pkmsg stanzas — with the
+    // account signature key, since recipients need it to check our signature.
+    accountEnc: encodeSignedDeviceIdentity(signedAccount, true),
+    platform:   (platformNode && platformNode.attrs && platformNode.attrs.name) || null,
+    deviceIndex,
+    keyIndex
+  };
+}
+
+module.exports = {
+  configureSuccessfulPairing,
+  encodeSignedDeviceIdentity,
+  readFields,
+  WA_ADV_ACCOUNT_SIG_PREFIX,
+  WA_ADV_DEVICE_SIG_PREFIX,
+  WA_ADV_HOSTED_ACCOUNT_SIG_PREFIX
+};

package/lib/HistorySyncHandler.js

@@ -441,9 +441,14 @@ function downloadUrl(url) {
     const driver = parsed.protocol === 'https:' ? https : http;
     const chunks = [];
 
+    // History only ever reaches a companion device, and the CDN treats a
+    // companion as a browser: it wants an Origin, and a mobile WhatsApp
+    // User-Agent against a web-issued blob is a mismatch it can refuse.
     const req = driver.get(url, {
       headers: {
-        'User-Agent': 'WhatsApp/2.24.20.82 A',
+        'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
+                      '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+        'Origin':     'https://web.whatsapp.com',
         'Accept':     '*/*'
       }
     }, (res) => {

package/lib/MediaService.js

@@ -19,6 +19,48 @@ const MEDIA_PATH = {
   gif:      { path: 'mms/gif',      keyName: 'WhatsApp Video Keys' }
 };
 
+// The web client does not have a path per media type. A sticker is uploaded to
+// the image endpoint, a GIF and a voice note to the video and audio ones — the
+// distinction lives in the message protobuf, not in the URL. Uploading a
+// sticker to /mms/sticker as a companion gets a 404 from the CDN.
+//
+// The encryption key names are unchanged; those come from the media type and
+// have nothing to do with the endpoint.
+const WEB_MEDIA_PATH = {
+  image:    'mms/image',
+  video:    'mms/video',
+  audio:    'mms/audio',
+  ptt:      'mms/audio',
+  document: 'mms/document',
+  sticker:  'mms/image',
+  gif:      'mms/video'
+};
+
+const WEB_ORIGIN_HEADER = 'https://web.whatsapp.com';
+const WEB_USER_AGENT =
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) ' +
+  'Chrome/120.0.0.0 Safari/537.36';
+
+// A companion is a browser as far as the CDN is concerned: it wants an Origin,
+// and a mobile WhatsApp User-Agent on a web-issued auth token is a mismatch it
+// can reject. A primary sends neither, exactly as before.
+function mediaHeaders(web) {
+  if (!web) {
+    const d = getDeviceConfig();
+    return {
+      'User-Agent': d.os === 'android'
+        ? `WhatsApp/${d.version || '2.26.7.75'} A`
+        : `WhatsApp/${d.version || '2.26.7.75'} iOS/${d.osVersion} Device/${d.model}`
+    };
+  }
+  return { 'User-Agent': WEB_USER_AGENT, 'Origin': WEB_ORIGIN_HEADER };
+}
+
+function mediaPathFor(mediaType, web) {
+  if (web) return WEB_MEDIA_PATH[mediaType] || (MEDIA_PATH[mediaType] || {}).path;
+  return (MEDIA_PATH[mediaType] || {}).path;
+}
+
 const EXPANDED_SIZE = 112;
 const IV_LEN        = 16;
 const KEY_LEN       = 32;
@@ -83,9 +125,11 @@ function decryptMedia(encryptedWithMac, mediaKey, keyName) {
 // retried with the fresh credentials. Without this a token that expires between
 // the TTL check and the upload burns through every host and fails permanently
 // ("connection expired"), because each retry reuses the same stale auth.
-async function uploadMedia(mediaType, data, hosts, auth, refreshAuth) {
+async function uploadMedia(mediaType, data, hosts, auth, refreshAuth, opts) {
   const typeInfo = MEDIA_PATH[mediaType];
   if (!typeInfo) throw new Error('Unknown media type: ' + mediaType);
+  const web       = !!(opts && opts.web);
+  const uploadPath = mediaPathFor(mediaType, web);
 
   const mediaKey        = crypto.randomBytes(32);
   const plaintext       = Buffer.isBuffer(data) ? data : fs.readFileSync(data);
@@ -115,7 +159,7 @@ async function uploadMedia(mediaType, data, hosts, auth, refreshAuth) {
     for (const host of currentHosts) {
       let res;
       try {
-        res = await _tryUpload(host, typeInfo.path, token, authEncoded, encrypted);
+        res = await _tryUpload(host, uploadPath, token, authEncoded, encrypted, web);
       } catch (_) {
         continue;
       }
@@ -146,7 +190,7 @@ async function uploadMedia(mediaType, data, hosts, auth, refreshAuth) {
 
 // Resolves { status, body } — status 0 marks a transport-level failure, so the
 // caller can tell an expired auth (4xx) apart from an unreachable host.
-function _tryUpload(host, mediaPath, token, auth, encrypted) {
+function _tryUpload(host, mediaPath, token, auth, encrypted, web) {
   return new Promise((resolve) => {
     const hostname = typeof host === 'string' ? host : host.hostname;
     const urlPath  = `/${mediaPath}/${token}?auth=${auth}&token=${token}`;
@@ -156,12 +200,11 @@ function _tryUpload(host, mediaPath, token, auth, encrypted) {
       port:    443,
       path:    urlPath,
       method:  'POST',
-      headers: {
+      headers: Object.assign({
         'Content-Type':   'application/octet-stream',
         'Content-Length': encrypted.length,
-        'Accept':         'application/json',
-        'User-Agent':     (() => { const d = getDeviceConfig(); return d.os === 'android' ? `WhatsApp/${d.version || '2.26.7.75'} A` : `WhatsApp/${d.version || '2.26.7.75'} iOS/${d.osVersion} Device/${d.model}`; })()
-      }
+        'Accept':         'application/json'
+      }, mediaHeaders(web))
     };
 
     const req = https.request(options, (res) => {
@@ -180,17 +223,20 @@ function _tryUpload(host, mediaPath, token, auth, encrypted) {
   });
 }
 
-async function downloadMedia(url, mediaKey, keyName) {
-  const encrypted = await _httpGet(url);
+async function downloadMedia(url, mediaKey, keyName, opts) {
+  const encrypted = await _httpGet(url, opts);
   return decryptMedia(encrypted, Buffer.from(mediaKey), keyName);
 }
 
-function _httpGet(url) {
+// The CDN applies the same Origin check on the way down as on the way up, so a
+// companion has to identify itself as a browser here too.
+function _httpGet(url, opts) {
   return new Promise((resolve, reject) => {
     const lib = url.startsWith('https') ? https : http;
-    lib.get(url, (res) => {
+    const web = !!(opts && opts.web);
+    lib.get(url, { headers: mediaHeaders(web) }, (res) => {
       if (res.statusCode === 301 || res.statusCode === 302) {
-        return _httpGet(res.headers.location).then(resolve).catch(reject);
+        return _httpGet(res.headers.location, opts).then(resolve).catch(reject);
       }
       const chunks = [];
       res.on('data', c => chunks.push(c));

package/lib/PairingCode.js

@@ -0,0 +1,198 @@
+'use strict';
+
+// Pairing by 8-character code, the alternative to scanning a QR.
+//
+// The account owner opens Linked Devices on their phone, picks "Link with phone
+// number instead", and types in the code this module generates. That code is
+// never sent to the server in the clear: it is a password, and both sides run
+// it through PBKDF2 to agree on a key that wraps the ephemeral public keys they
+// exchange. Someone who watches the whole conversation still cannot derive the
+// shared secret without the eight characters the human typed.
+//
+// The exchange, in order:
+//
+//   1. companion_hello   — we send our ephemeral public key, encrypted under
+//                          the pairing code, plus our noise public key.
+//   2. (human types the code into their phone)
+//   3. companion_finish  — the server pushes the primary's wrapped ephemeral
+//                          key and identity key. We unwrap, do two Diffie-
+//                          Hellmans, and derive adv_secret — the key the
+//                          primary's account signature will be verified with.
+//   4. pair-success      — the primary's signed device identity arrives; we
+//                          verify it, counter-sign, and reply.
+//
+// After that the server drops the connection with a 515 and the next one logs
+// in normally.
+
+const crypto = require('crypto');
+const curveJs = require('curve25519-js');
+
+// Crockford base32 minus the ambiguous characters — no I, O, U, and no 0.
+// Five random bytes become exactly eight characters.
+const CROCKFORD_CHARACTERS = '123456789ABCDEFGHJKLMNPQRSTVWXYZ';
+
+function bytesToCrockford(buffer) {
+  let value = 0;
+  let bitCount = 0;
+  const out = [];
+
+  for (const element of buffer) {
+    value = (value << 8) | (element & 0xff);
+    bitCount += 8;
+    while (bitCount >= 5) {
+      out.push(CROCKFORD_CHARACTERS.charAt((value >>> (bitCount - 5)) & 31));
+      bitCount -= 5;
+    }
+  }
+  if (bitCount > 0) {
+    out.push(CROCKFORD_CHARACTERS.charAt((value << (5 - bitCount)) & 31));
+  }
+  return out.join('');
+}
+
+function generatePairingCode() {
+  return bytesToCrockford(crypto.randomBytes(5));
+}
+
+/**
+ * PBKDF2-SHA256 over the pairing code, 2^17 iterations, 32-byte output.
+ *
+ * The iteration count is what makes the eight characters worth anything: it
+ * costs an attacker who captured the handshake roughly that many hashes per
+ * guess across a 32^8 space.
+ */
+function derivePairingCodeKey(pairingCode, salt) {
+  return new Promise((resolve, reject) => {
+    crypto.pbkdf2(Buffer.from(String(pairingCode), 'utf8'), salt, 2 << 16, 32, 'sha256',
+      (err, key) => (err ? reject(err) : resolve(key)));
+  });
+}
+
+function aesEncryptCTR(plaintext, key, iv) {
+  const c = crypto.createCipheriv('aes-256-ctr', key, iv);
+  return Buffer.concat([c.update(plaintext), c.final()]);
+}
+
+function aesDecryptCTR(ciphertext, key, iv) {
+  const d = crypto.createDecipheriv('aes-256-ctr', key, iv);
+  return Buffer.concat([d.update(ciphertext), d.final()]);
+}
+
+function aesEncryptGCM(plaintext, key, iv, aad) {
+  const c = crypto.createCipheriv('aes-256-gcm', key, iv);
+  c.setAAD(aad || Buffer.alloc(0));
+  return Buffer.concat([c.update(plaintext), c.final(), c.getAuthTag()]);
+}
+
+function hkdf(input, length, info, salt) {
+  const { hkdf: nobleHkdf } = require('@noble/hashes/hkdf');
+  const { sha256 } = require('@noble/hashes/sha256');
+  return Buffer.from(nobleHkdf(
+    sha256,
+    input,
+    salt || Buffer.alloc(32),
+    info ? Buffer.from(info, 'utf8') : Buffer.alloc(0),
+    length
+  ));
+}
+
+function stripKeyPrefix(pub) {
+  if (pub && pub.length === 33 && pub[0] === 0x05) return pub.slice(1);
+  return pub;
+}
+
+function sharedKey(priv, pub) {
+  return Buffer.from(curveJs.sharedKey(stripKeyPrefix(priv), stripKeyPrefix(pub)));
+}
+
+function generateEphemeralKeyPair() {
+  const kp = curveJs.generateKeyPair(crypto.randomBytes(32));
+  return { private: Buffer.from(kp.private), public: Buffer.from(kp.public) };
+}
+
+/**
+ * Wrap our ephemeral public key for the companion_hello node.
+ *
+ * Layout: salt(32) || iv(16) || AES-256-CTR(ephemeral public key, 32)
+ * The primary reproduces the key from the code the human typed and unwraps it.
+ */
+async function buildWrappedEphemeralPub(pairingCode, ephemeralPublicKey) {
+  const salt     = crypto.randomBytes(32);
+  const iv       = crypto.randomBytes(16);
+  const key      = await derivePairingCodeKey(pairingCode, salt);
+  const ciphered = aesEncryptCTR(stripKeyPrefix(ephemeralPublicKey), key, iv);
+  return Buffer.concat([salt, iv, ciphered]);
+}
+
+/** The inverse, applied to the primary's wrapped ephemeral key. */
+async function decipherLinkPublicKey(data, pairingCode) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  if (buf.length < 80) {
+    throw new Error('link_code_pairing_wrapped_primary_ephemeral_pub too short: ' + buf.length);
+  }
+  const salt      = buf.slice(0, 32);
+  const iv        = buf.slice(32, 48);
+  const payload   = buf.slice(48, 80);
+  const secretKey = await derivePairingCodeKey(pairingCode, salt);
+  return aesDecryptCTR(payload, secretKey, iv);
+}
+
+/**
+ * Stage 3. Given what the server pushed, derive adv_secret and produce the
+ * key bundle the primary needs to finish the link.
+ *
+ * adv_secret is the whole point of the exchange: every subsequent proof that
+ * this device belongs to the account is an HMAC under it.
+ *
+ * @returns {{advSecretKey: string, wrappedKeyBundle: Buffer}}
+ */
+async function buildCompanionFinishBundle(opts) {
+  const {
+    pairingCode,
+    pairingEphemeralPrivate,
+    primaryEphemeralPubWrapped,
+    primaryIdentityPub,
+    identityKeyPair
+  } = opts;
+
+  const codePairingPublicKey = await decipherLinkPublicKey(primaryEphemeralPubWrapped, pairingCode);
+  const companionSharedKey   = sharedKey(pairingEphemeralPrivate, codePairingPublicKey);
+
+  const random       = crypto.randomBytes(32);
+  const linkCodeSalt = crypto.randomBytes(32);
+  const expanded     = hkdf(companionSharedKey, 32, 'link_code_pairing_key_bundle_encryption_key', linkCodeSalt);
+
+  const encryptPayload = Buffer.concat([
+    stripKeyPrefix(identityKeyPair.public),
+    stripKeyPrefix(primaryIdentityPub),
+    random
+  ]);
+  const encryptIv = crypto.randomBytes(12);
+  const encrypted = aesEncryptGCM(encryptPayload, expanded, encryptIv, Buffer.alloc(0));
+
+  const identitySharedKey = sharedKey(identityKeyPair.private, primaryIdentityPub);
+  const identityPayload   = Buffer.concat([companionSharedKey, identitySharedKey, random]);
+  const advSecretKey      = hkdf(identityPayload, 32, 'adv_secret').toString('base64');
+
+  return {
+    advSecretKey,
+    wrappedKeyBundle: Buffer.concat([linkCodeSalt, encryptIv, encrypted])
+  };
+}
+
+module.exports = {
+  CROCKFORD_CHARACTERS,
+  bytesToCrockford,
+  generatePairingCode,
+  generateEphemeralKeyPair,
+  derivePairingCodeKey,
+  buildWrappedEphemeralPub,
+  decipherLinkPublicKey,
+  buildCompanionFinishBundle,
+  aesEncryptCTR,
+  aesDecryptCTR,
+  aesEncryptGCM,
+  hkdf,
+  sharedKey,
+  stripKeyPrefix
+};

package/lib/WebSocketStream.js

@@ -0,0 +1,98 @@
+'use strict';
+
+// A WebSocket that behaves like a net.Socket.
+//
+// NoiseSocket was written against a raw TLS socket to g.whatsapp.net and knows
+// nothing about WebSockets. Rather than fork it, this wraps `ws` in the same
+// small surface NoiseSocket already uses — write/destroy/setKeepAlive plus the
+// connect/data/error/close events — so a single handshake implementation drives
+// both transports.
+//
+// The length framing is unchanged: even inside a WebSocket message WhatsApp
+// still prefixes each frame with three big-endian length bytes, so the existing
+// buffer loop applies as-is.
+
+const EventEmitter = require('events');
+const { WEB_SOCKET_URL, WEB_ORIGIN } = require('./constants');
+
+function loadWs() {
+  try {
+    return require('ws');
+  } catch (_) {
+    throw new Error(
+      "The 'ws' package is required for WhatsApp Web mode. Install it with: npm install ws"
+    );
+  }
+}
+
+class WebSocketStream extends EventEmitter {
+  constructor(opts) {
+    super();
+    opts = opts || {};
+    this._url     = opts.url     || WEB_SOCKET_URL;
+    this._origin  = opts.origin  || WEB_ORIGIN;
+    this._ws      = null;
+    this._closed  = false;
+    this._opened  = false;
+  }
+
+  connect() {
+    const WebSocket = loadWs();
+    this._ws = new WebSocket(this._url, {
+      origin:  this._origin,
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
+                      '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+      },
+      handshakeTimeout: 20000
+    });
+
+    this._ws.on('open', () => {
+      this._opened = true;
+      this.emit('connect');
+    });
+
+    // ws hands us a Buffer for binary frames; normalise anything else so the
+    // caller only ever deals in Buffers.
+    this._ws.on('message', (data) => {
+      this.emit('data', Buffer.isBuffer(data) ? data : Buffer.from(data));
+    });
+
+    this._ws.on('error', (err) => this.emit('error', err));
+
+    this._ws.on('close', () => {
+      if (this._closed) return;
+      this._closed = true;
+      this.emit('close');
+    });
+
+    return this;
+  }
+
+  write(buf) {
+    if (!this._ws || this._ws.readyState !== 1) return false;
+    this._ws.send(buf);
+    return true;
+  }
+
+  // net.Socket parity — a WebSocket has no equivalent knob, and `ws` sends its
+  // own pings, so this is deliberately a no-op rather than an error.
+  setKeepAlive() { /* no-op */ }
+
+  destroy() {
+    if (!this._ws) return;
+    try {
+      // terminate() rather than close(): we are tearing down, not negotiating,
+      // and a half-open socket here would leave the client waiting on a reply
+      // that is never coming.
+      this._ws.terminate();
+    } catch (_) {}
+    this._ws = null;
+    if (!this._closed) {
+      this._closed = true;
+      this.emit('close');
+    }
+  }
+}
+
+module.exports = { WebSocketStream };