whalibmob 5.10.1 → 5.10.5

package/README.md

@@ -1449,20 +1449,26 @@ client.on('account_restriction', (r) => {
 > client-side shortens it; the only thing that helps is not sending more
 > unanswered first messages while it is on.
 
-> [!WARNING]
-> **Some servers answer this query in Argo, not JSON.** Argo is Meta's binary
-> GraphQL encoding, and this library cannot read it. When that happens
-> `fetchReachoutTimelock()` throws with `err.mexFormat === 'argo'` and the raw
-> bytes on `err.mexPayload`.
+> [!NOTE]
+> **This transport answers in one of two encodings**, and the reply says which:
+> JSON, or Argo — Meta's compact binary encoding for GraphQL. Both are read.
+> WhatsApp sends Argo with its self-describing flag set, so it carries its own
+> field names and decodes without the GraphQL schema the query was written
+> against.
+>
+> Do not add a `format` attribute to the query in the hope of steering this — it
+> was tried against a live server, which responded by dropping the stanza
+> entirely and answering nothing.
 >
-> It never guesses. Reporting "not restricted" from an answer nobody decoded
-> would have you send more messages and make the restriction longer, so an
-> unreadable reply is an error rather than an all-clear.
+> Some accounts get an answer with no restriction data in it at all — a bare
+> `false` rather than a result. That throws, with the decoded value on
+> `err.mexDecoded`, rather than being reported as "not restricted": an
+> all-clear invented from an answer that never said so would have you send more
+> messages and lengthen the very restriction you were asking about.
 >
-> The `account_restriction` event is unaffected: the server *announces* a
-> restriction starting and lifting, and those announcements arrive as readable
-> JSON on a different route. Keep a listener attached and you will still be
-> told, with the countdown, without ever calling the query.
+> The `account_restriction` event does not depend on any of this. The server
+> *announces* a restriction starting and lifting, and those announcements carry
+> the countdown. Keep a listener attached and you are told either way.
 
 ### What Is Automatic vs What You Need to Do
 
@@ -3262,19 +3268,37 @@ For the numbers without the countdown:
 wa> /restriction --once
 ```
 
-If your server encodes this answer in Argo, the command says so rather than
-guessing — and points you at the announcements, which stay readable:
+To check the display without waiting to be restricted, `--demo` counts down a
+made-up restriction. Nothing is sent, nothing is asked of the server, and
+nothing is left behind when it ends:
+
+```sh
+wa> /restriction --demo
+  ──────────────────────────────────────────────────
+  status                RESTRICTED  (demo — not real)
+  reason                too many people you messaged blocked or reported you
+  remaining             05:00:00
+  ──────────────────────────────────────────────────
+  press any key to stop watching
+  restricted — 04:59:57 remaining
+```
+
+`--demo 90` uses ninety seconds instead of the default five hours, which is
+short enough to watch it reach zero and stop on its own.
+
+Some accounts get a reply that decodes cleanly but holds no restriction data.
+The command says that, rather than reading it as an all-clear:
 
 ```sh
 wa> /restriction
 checking account restriction...
-error: mex query 23983697327930364: the server answered in "argo" rather than JSON, which this library cannot read (10 bytes: 0402300c000002010303)
+error: mex query 23983697327930364: the server answered false rather than a result — this query returns no data for this account
 
-  The query itself worked — your server encodes this answer in a binary
-  format this library cannot read yet, so the countdown cannot be polled.
+  The reply was read successfully — it simply contains no restriction
+  data. This query returns nothing usable for your account.
 
   You will still be told about a restriction: the server announces one when
-  it starts and when it lifts, and those announcements do arrive readable.
+  it starts and when it lifts, and those announcements carry the countdown.
 ```
 
 An account that is fine says so and returns immediately:
@@ -3794,6 +3818,7 @@ wa> /quit
 | `/appstate --snapshot` | Re-read all app state from scratch |
 | `/restriction` | Account restriction status with a live countdown |
 | `/restriction --once` | Restriction status without the countdown |
+| `/restriction --demo [seconds]` | Fake countdown, to check the display |
 | `/limit` | Alias for `/restriction` |
 | `/ephemeral <jid> <seconds>` | Set disappearing messages timer for a chat |
 | `/ephemeral-default <seconds>` | Set global default ephemeral timer for new chats |

package/cli.js

@@ -478,6 +478,7 @@ const HELP = `
     /appstate  --snapshot                    re-read all of it from scratch
     /restriction                             account restriction + live countdown
     /restriction --once                      just the numbers, no countdown
+    /restriction --demo [seconds]            fake countdown to check the display
     /ephemeral         <jid> <seconds>        set disappearing timer for chat
     /ephemeral-default <seconds>             set default timer for ALL new chats
     /block     <jid>                         block contact
@@ -1479,6 +1480,34 @@ async function handleLine(line) {
 
       case '/restriction':
       case '/limit': {
+        // --demo feeds a made-up restriction into this session and counts it
+        // down, so the display can be checked without waiting to be restricted.
+        // Nothing is sent and nothing is asked of the server.
+        const demoAt = p.indexOf('--demo');
+        if (demoAt !== -1) {
+          const secs = parseInt(p[demoAt + 1], 10) || 5 * 3600;
+          const { parseTimelockPayload } = require('./lib/ReachoutTimelock');
+          if (!_client) { fail('/restriction --demo needs a client; use /connect first'); break; }
+          const fake = parseTimelockPayload({
+            is_active: true,
+            time_enforcement_ends: String(Math.floor(Date.now() / 1000) + secs),
+            enforcement_type: 'BIZ_QUALITY'
+          });
+          const shown = _client._setReachoutTimelock(fake, 'demo');
+          hr();
+          kv('status',    'RESTRICTED  (demo — not real)');
+          kv('reason',    shown.reason);
+          kv('remaining', shown.remaining);
+          hr();
+          _rl && _rl.pause();
+          await countdown(_client, shown);
+          _rl && _rl.resume();
+          // Leave nothing behind that a later check could mistake for real.
+          _client._reachoutTimelock = null;
+          out('  demo over — nothing was recorded');
+          break;
+        }
+
         requireConn();
         const watch = !p.includes('--once');
         out('checking account restriction...');
@@ -1487,19 +1516,19 @@ async function handleLine(line) {
           st = await _client.fetchReachoutTimelock();
         } catch (e) {
           fail(e.message);
-          if (e.mexFormat) {
+          if (e.mexDecoded !== undefined) {
             out('');
-            out('  The query itself worked — your server encodes this answer in a binary');
-            out('  format this library cannot read yet, so the countdown cannot be polled.');
+            out('  The reply was read successfully — it simply contains no restriction');
+            out('  data. This query returns nothing usable for your account.');
             out('');
             out('  You will still be told about a restriction: the server announces one when');
-            out('  it starts and when it lifts, and those announcements do arrive readable.');
+            out('  it starts and when it lifts, and those announcements carry the countdown.');
             out('  Leave the session connected and watch for:');
             out('    ACCOUNT RESTRICTED — <reason>, HH:MM:SS remaining');
+          } else if (e.mexFormat) {
             out('');
-            out('  The payload above is worth keeping. Run this again while the account IS');
-            out('  restricted: the two payloads differ only where the answer differs, which');
-            out('  is what makes this format readable without its schema.');
+            out('  The query worked, but the reply is in an encoding that could not be');
+            out('  decoded. Paste the bytes above when reporting this.');
           } else {
             out('');
             out('  If the reply is sketched above, paste that line when reporting this —');

package/index.js

@@ -14,6 +14,7 @@ const { MessageSender, makeJid, generateMessageId } = require('./lib/messages/Me
 const { GroupParticipantResult, GroupJoinRequest } = require('./lib/GroupParticipant');
 const { AppStateStore, COLLECTIONS: APP_STATE_COLLECTIONS } = require('./lib/appstate/AppStateStore');
 const ReachoutTimelock = require('./lib/ReachoutTimelock');
+const { decodeArgo, tryDecodeArgo } = require('./lib/argo/ArgoDecoder');
 const AppStateSync = require('./lib/appstate/AppStateSync');
 const { PATCH_INTEGRITY: LT_HASH } = require('./lib/appstate/LTHash');
 const {
@@ -113,6 +114,9 @@ module.exports = {
   LT_HASH,
   // Account restriction
   ReachoutTimelock,
+  // Argo (the binary encoding the GraphQL transport may answer in)
+  decodeArgo,
+  tryDecodeArgo,
   // Auth utilities
   makeCacheableSignalKeyStore,
   addTransactionCapability,

package/lib/Client.js

@@ -14,6 +14,7 @@ const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts } = requi
 const { BinaryNode }      = require('./BinaryNode');
 const { AppStateStore, COLLECTIONS } = require('./appstate/AppStateStore');
 const ReachoutTimelock = require('./ReachoutTimelock');
+const { decodeArgo }   = require('./argo/ArgoDecoder');
 const AppStateSync  = require('./appstate/AppStateSync');
 const SyncdProto    = require('./appstate/SyncdProto');
 const AppMutations  = require('./appstate/Mutations');
@@ -4961,32 +4962,18 @@ class WhalibmobClient extends EventEmitter {
   async _mexQuery(queryId, variables, dataPath) {
     const body = Buffer.from(JSON.stringify({ variables: variables || {} }), 'utf8');
 
-    const send = (askForJson) => {
-      const attrs = { query_id: String(queryId) };
-      // Newer servers answer this transport in Argo, Meta's binary GraphQL
-      // encoding, which nothing here can read. The reply labels its own format,
-      // so the format is evidently negotiable — ask for the one we can parse.
-      // A server that does not know the attribute ignores it, and one that
-      // refuses the stanza over it is handled below.
-      if (askForJson) attrs.format = 'json';
-      return this._sendIq(new BinaryNode('iq', {
-        id:    this._genMsgId(),
-        to:    's.whatsapp.net',
-        type:  'get',
-        xmlns: 'w:mex'
-      }, [new BinaryNode('query', attrs, body)]));
-    };
-
-    const hinted = this._mexJsonHintWorks !== false;
-    let resp     = await send(hinted);
-
-    // The hint is the only thing that changed, so a refusal means the server
-    // does not accept it. Drop it for this session and ask again plainly.
-    if (hinted && resp && resp.attrs && resp.attrs.type === 'error') {
-      this._mexJsonHintWorks = false;
-      _whaDbg('[DBG] MEX format=json hint refused — retrying without it');
-      resp = await send(false);
-    }
+    // The <query> node carries the query id and nothing else.
+    //
+    // Asking for a format here was tried and is wrong: a `format="json"`
+    // attribute makes the server drop the stanza on the floor — no reply at
+    // all, where without it there is at least an answer. It does not ignore
+    // what it does not recognise, so nothing speculative belongs on this node.
+    const resp = await this._sendIq(new BinaryNode('iq', {
+      id:    this._genMsgId(),
+      to:    's.whatsapp.net',
+      type:  'get',
+      xmlns: 'w:mex'
+    }, [new BinaryNode('query', { query_id: String(queryId) }, body)]));
 
     if (!resp) throw new Error('mex query ' + queryId + ': no reply from server (IQ timed out)');
 
@@ -5013,15 +5000,56 @@ class WhalibmobClient extends EventEmitter {
       return dataPath ? (json.data && json.data[dataPath]) : json.data;
     }
 
-    // The query itself worked — this is purely about how the answer was
-    // encoded, and saying so is the difference between a fixable report and a
-    // shrug.
+    // Not JSON, so the other encoding this transport uses: Argo, which is what
+    // newer servers answer with. It carries its own field names, so it decodes
+    // without the GraphQL schema the query was written against.
     const resultNode = findChildDeep(resp, 'result');
     const format     = resultNode && resultNode.attrs && resultNode.attrs.format;
+    const raw        = resultNode ? getNodeContent(resultNode) : null;
+
+    // Only when the server said so. Guessing that unlabelled bytes are Argo
+    // turns "this reply is not what I expected" into a misleading complaint
+    // about a format that was never claimed.
+    if (raw && raw.length && format && String(format).toLowerCase() === 'argo') {
+      let decoded;
+      try {
+        decoded = decodeArgo(raw);
+      } catch (e) {
+        const err = new Error('mex query ' + queryId + ': the reply is ' +
+          (format ? '"' + format + '"' : 'binary') + ' and could not be decoded — ' +
+          e.message + ' (' + raw.length + ' bytes: ' + raw.toString('hex') + ')');
+        err.mexFormat  = format ? String(format) : null;
+        err.mexPayload = raw;
+        throw err;
+      }
+      _whaDbg('[DBG] MEX_ARGO decoded ' + JSON.stringify(decoded));
+
+      if (decoded && typeof decoded === 'object') {
+        if (decoded.errors && decoded.errors.length) {
+          throw new Error('mex query ' + queryId + ': ' +
+            decoded.errors.map(e => (e && e.message) || 'unknown error').join(', '));
+        }
+        if (decoded.data !== undefined) {
+          return dataPath ? (decoded.data && decoded.data[dataPath]) : decoded.data;
+        }
+        return dataPath ? decoded[dataPath] : decoded;
+      }
+
+      // The server answered something that is not a GraphQL result at all —
+      // a bare boolean, most often. There is no data in it to return, and
+      // saying so beats handing back a shape the caller will misread.
+      const err = new Error('mex query ' + queryId + ': the server answered ' +
+        JSON.stringify(decoded) + ' rather than a result — this query returns ' +
+        'no data for this account');
+      err.mexFormat  = format ? String(format) : null;
+      err.mexPayload = raw;
+      err.mexDecoded = decoded;
+      throw err;
+    }
+
     if (format && String(format).toLowerCase() !== 'json') {
-      const raw = getNodeContent(resultNode);
       const err = new Error('mex query ' + queryId + ': the server answered in "' +
-        format + '" rather than JSON, which this library cannot read' +
+        format + '", which this library cannot read' +
         (raw ? ' (' + raw.length + ' bytes: ' + raw.toString('hex') + ')' : ''));
       err.mexFormat  = String(format);
       err.mexPayload = raw || null;
@@ -5094,13 +5122,27 @@ class WhalibmobClient extends EventEmitter {
   }
 
   // Internal: parse newsletter response from w:mex IQ result
+  //
+  // Every newsletter call travels the same transport as the restriction query,
+  // so a server that answers that one in Argo answers these in Argo too. This
+  // used to swallow that and return null, which reads as "no such newsletter"
+  // rather than "this reply is in an encoding nothing here can read" — the
+  // difference between a shrug and something a caller can act on.
   _parseNewsletterResponse(resp) {
     try {
-      const resultNode = findChild(resp, 'result');
-      if (!resultNode) return null;
-      const buf = getNodeContent(resultNode);
-      if (!buf) return null;
-      const json = JSON.parse(buf.toString('utf8'));
+      const json = this._mexJsonFrom(resp);
+      if (!json) {
+        const resultNode = findChildDeep(resp, 'result');
+        const format     = resultNode && resultNode.attrs && resultNode.attrs.format;
+        if (format && String(format).toLowerCase() !== 'json') {
+          _whaDbg('[DBG] NEWSLETTER reply format=' + format + ' — cannot decode');
+          const err = new Error('the server answered in "' + format +
+            '" rather than JSON, which this library cannot read');
+          err.mexFormat = String(format);
+          throw err;
+        }
+        return null;
+      }
       const nl = json && (json.newsletter || (json.data && json.data.xwa2_newsletter));
       if (!nl) return null;
       const meta = nl.metadata || nl;
@@ -5111,7 +5153,8 @@ class WhalibmobClient extends EventEmitter {
         subscriberCount: nl.subscribers_count || meta.subscriber_count || 0,
         creationTime:    nl.creation_time || meta.creation_time || 0
       };
-    } catch (_) {
+    } catch (err) {
+      if (err && err.mexFormat) throw err;
       return null;
     }
   }

package/lib/argo/ArgoDecoder.js

@@ -0,0 +1,240 @@
+'use strict';
+
+// Argo — the binary encoding WhatsApp's GraphQL transport answers in.
+//
+// A w:mex reply can come back as JSON or as Argo; the <result> node says which.
+// Argo is normally decoded against the schema of the query that asked, which a
+// client outside Meta does not have. But a message can set a SelfDescribing
+// flag, and then it carries its own field names and types — which is what
+// WhatsApp sends, and what makes this readable at all.
+//
+// Only the self-describing form is implemented. A schema-typed message is
+// refused rather than guessed at.
+//
+// Layout:
+//   [header bitset][block][block]…[core]
+// where each block is a length label followed by that many bytes, and the core
+// is the last one. Values in the core are Labels — zigzag ULEB128 integers —
+// that either carry a small value outright or point into a block.
+
+// ─── labels ──────────────────────────────────────────────────────────────────
+//
+// A label is one signed integer doing several jobs at once. Non-negative is a
+// length or a boolean; the three values below are markers; anything lower is a
+// backreference to a value already seen.
+const LABEL_NULL   = -1;
+const LABEL_ABSENT = -2;
+const LABEL_ERROR  = -3;
+// -4 is the first backreference and means "the first value in this block".
+const BACKREF_BASE = -4;
+
+// Self-describing type markers, as label values.
+const MARKER = {
+  NULL:   -1,
+  FALSE:   0,
+  TRUE:    1,
+  OBJECT:  2,
+  LIST:    3,
+  STRING:  4,
+  BYTES:   5,
+  INT:     6,
+  FLOAT:   7
+};
+
+// Header flag bit positions.
+const FLAG_INLINE_EVERYTHING = 0;
+const FLAG_SELF_DESCRIBING   = 1;
+
+class Reader {
+  constructor(buf) {
+    this.buf = buf;
+    this.pos = 0;
+  }
+  get done()      { return this.pos >= this.buf.length; }
+  byte() {
+    if (this.pos >= this.buf.length) throw new Error('argo: ran off the end of the message');
+    return this.buf[this.pos++];
+  }
+  peek()          { return this.buf[this.pos]; }
+  take(n) {
+    if (n < 0 || this.pos + n > this.buf.length) {
+      throw new Error('argo: asked for ' + n + ' bytes with ' +
+        (this.buf.length - this.pos) + ' left');
+    }
+    const out = this.buf.slice(this.pos, this.pos + n);
+    this.pos += n;
+    return out;
+  }
+  // ULEB128, then zigzag back to signed.
+  label() {
+    let value = 0n, shift = 0n;
+    for (;;) {
+      const b = this.byte();
+      value |= BigInt(b & 0x7f) << shift;
+      if (!(b & 0x80)) break;
+      shift += 7n;
+      if (shift > 63n) throw new Error('argo: label is too long to be a number');
+    }
+    const signed = (value >> 1n) ^ -(value & 1n);
+    return Number(signed);
+  }
+}
+
+function readHeader(reader) {
+  let bits = 0, shift = 0, more = true;
+  while (more) {
+    const b = reader.byte();
+    bits |= (b >> 1) << shift;
+    shift += 7;
+    more = (b & 1) === 1;
+  }
+  return {
+    bits,
+    selfDescribing:   !!(bits >> FLAG_SELF_DESCRIBING   & 1),
+    inlineEverything: !!(bits >> FLAG_INLINE_EVERYTHING & 1)
+  };
+}
+
+// A block holds the bulky values — strings, byte arrays, numbers — with the
+// core referring to them in order. Blocks are handed out in the order their
+// types are first needed, which is why they are taken from a queue rather than
+// looked up by name.
+class BlockQueue {
+  constructor(blocks, core, inlineEverything) {
+    this.blocks = blocks;
+    this.core   = core;
+    this.inline = inlineEverything;
+    this.next   = 0;
+    this.byKey  = new Map();
+  }
+  for(key) {
+    if (this.inline) return { reader: this.core, seen: [] };
+    if (!this.byKey.has(key)) {
+      const buf = this.blocks[this.next++];
+      if (buf === undefined) throw new Error('argo: message is missing a block for ' + key);
+      this.byKey.set(key, { reader: new Reader(buf), seen: [] });
+    }
+    return this.byKey.get(key);
+  }
+}
+
+function decodeArgo(bytes) {
+  const buf    = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  const reader = new Reader(buf);
+  const header = readHeader(reader);
+
+  if (!header.selfDescribing) {
+    const err = new Error('argo: this message is encoded against a GraphQL schema ' +
+      'rather than describing itself, so it cannot be read without that schema');
+    err.needsSchema = true;
+    throw err;
+  }
+
+  const blocks = [];
+  if (header.inlineEverything) {
+    blocks.push(reader.take(buf.length - reader.pos));
+  } else {
+    while (!reader.done) {
+      const len = reader.label();
+      if (len < 0) throw new Error('argo: block length cannot be ' + len);
+      blocks.push(reader.take(len));
+    }
+  }
+  if (!blocks.length) throw new Error('argo: message has no core');
+
+  // The core is the last block, and every other block feeds it.
+  const core   = new Reader(blocks[blocks.length - 1]);
+  const queue  = new BlockQueue(blocks.slice(0, -1), core, header.inlineEverything);
+
+  return readValue(core, queue);
+}
+
+// One length-prefixed value out of a block, with backreferences resolved.
+//
+// The same string written twice is written once and pointed at the second time,
+// which is most of why this format is small. A backreference that points at
+// nothing means the message and our reading of it have diverged.
+function readBlockValue(core, queue, key, convert) {
+  const block = queue.for(key);
+  const label = core.label();
+  if (label <= BACKREF_BASE) {
+    const idx = -label + BACKREF_BASE;
+    if (idx < 0 || idx >= block.seen.length) {
+      throw new Error('argo: backreference ' + label + ' points outside ' + key);
+    }
+    return block.seen[idx];
+  }
+  if (label < 0) throw new Error('argo: ' + key + ' cannot have label ' + label);
+  const value = convert(block.reader.take(label));
+  block.seen.push(value);
+  return value;
+}
+
+function readValue(core, queue) {
+  const marker = core.label();
+
+  switch (marker) {
+    case MARKER.NULL:   return null;
+    case MARKER.FALSE:  return false;
+    case MARKER.TRUE:   return true;
+
+    case MARKER.OBJECT: {
+      const count = core.label();
+      if (count < 0) throw new Error('argo: object cannot have ' + count + ' fields');
+      const out = {};
+      for (let i = 0; i < count; i++) {
+        const name = readBlockValue(core, queue, 'String', b => b.toString('utf8'));
+        out[name]  = readValue(core, queue);
+      }
+      return out;
+    }
+
+    case MARKER.LIST: {
+      const count = core.label();
+      if (count < 0) throw new Error('argo: list cannot have ' + count + ' items');
+      const out = [];
+      for (let i = 0; i < count; i++) out.push(readValue(core, queue));
+      return out;
+    }
+
+    case MARKER.STRING: return readBlockValue(core, queue, 'String', b => b.toString('utf8'));
+    case MARKER.BYTES:  return readBlockValue(core, queue, 'Bytes',  b => Buffer.from(b));
+
+    // An integer lives entirely in its block — the core spends nothing on it.
+    case MARKER.INT: {
+      const block = queue.for('Varint');
+      return block.reader.label();
+    }
+
+    case MARKER.FLOAT: {
+      const block = queue.for('Float');
+      return block.reader.take(8).readDoubleLE(0);
+    }
+
+    default:
+      if (marker === LABEL_ABSENT) return undefined;
+      if (marker === LABEL_ERROR)  return readValue(core, queue);
+      throw new Error('argo: unknown type marker ' + marker);
+  }
+}
+
+/**
+ * Decode an Argo message, or return null when it is not one this can read.
+ *
+ * Never throws: a caller reaching for this already has a reply it could not
+ * parse, and a second failure on top of that is not news. `decodeArgo` is there
+ * for when the reason matters.
+ */
+function tryDecodeArgo(bytes) {
+  try { return decodeArgo(bytes); }
+  catch (_) { return null; }
+}
+
+module.exports = {
+  decodeArgo,
+  tryDecodeArgo,
+  MARKER,
+  LABEL_NULL,
+  LABEL_ABSENT,
+  LABEL_ERROR
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whalibmob",
-  "version": "5.10.1",
+  "version": "5.10.5",
   "description": "WhatsApp library for interaction with WhatsApp Mobile API no web",
   "author": "Kunboruto20",
   "main": "index.js",