whalibmob 5.11.0 → 5.12.0

package/.env.example

@@ -80,6 +80,15 @@
 # WA_SOCKS_LIB=/absolute/path/to/socks/build/index.js
 
 
+# ─── Registration funnel telemetry ───────────────────────────────────────────
+# Registration reports the screens it passes through to WhatsApp's /client_log,
+# the way the phone clients do. It is fire-and-forget — every failure is
+# swallowed and it can never take a registration down.
+#
+# Set to 0 to send none of it.
+# WA_FUNNEL_LOG=0
+
+
 # ─── Frida attestation bridge ────────────────────────────────────────────────
 # Host running the Frida attestation helper (see the frida/ directory).
 # Leave unset to disable the bridge.

package/README.md

@@ -154,6 +154,7 @@ npm install -g whalibmob
     - [Knowing Which Mode You Are In](#knowing-which-mode-you-are-in)
     - [Two Sessions on One Number](#two-sessions-on-one-number)
   - [The Number WhatsApp Files Your Account Under](#the-number-whatsapp-files-your-account-under)
+  - [When Registration Is Refused for Consent](#when-registration-is-refused-for-consent)
   - [Routing Registration Through a Proxy](#routing-registration-through-a-proxy)
   - [Saving & Restoring Sessions](#saving--restoring-sessions)
   - [Signal Store Utilities](#signal-store-utilities)
@@ -306,6 +307,30 @@ if (result.status === 'ok') {
 }
 ```
 
+**When the code is not the end of it.** The server can answer a submitted code with a CAPTCHA, or with a demand for the account's two-step verification PIN. Neither is something the library can work out on its own, so both come back to you through optional handlers:
+
+```js
+const result = await verifyCode(store, '123456', {
+  // image and audio are Buffers, or null when that variant was not sent.
+  // Return the answer, or null to give up.
+  async solveCaptcha({ image, audio }) {
+    fs.writeFileSync('captcha.png', image)
+    return await askTheUser()
+  },
+
+  // The six-digit PIN set on the phone under
+  // Settings → Account → Two-step verification.
+  async twoFactorPin() {
+    return await askTheUser()
+  }
+})
+```
+
+Both are optional and both keep working when omitted — you get an error naming what was asked for instead of a silent failure, with the CAPTCHA blobs attached as `err.captcha`. A wrong CAPTCHA answer is replied to with another one, so `solveCaptcha` may be called several times. The CLI prompts for both, writing the image to a temp file first.
+
+> [!NOTE]
+> Registration reports the screens it passes through to WhatsApp's `/client_log`, the way the phone clients do — a client that registers in total silence does something no real installation does. It is fire-and-forget and every failure is swallowed, so it can never take a registration down. Set `WA_FUNNEL_LOG=0` to send none of it.
+
 ### Device Attestation with Frida (optional)
 
 WhatsApp's registration servers score every `/code` and `/register` request on how
@@ -863,6 +888,27 @@ if (probe.mismatch) {
 > [!NOTE]
 > The check costs nothing when things work — it runs only after a login has already been refused.
 
+## When Registration Is Refused for Consent
+
+Some numbers come back from `/register` like this:
+
+```json
+{ "login": "557176034186", "pending": "app_store_age", "reason": "consent", "status": "fail" }
+```
+
+The code was not refused and the account was found — WhatsApp is asking for an age signal that only a real app-store install carries, and will not finish without it. Brazilian numbers are where this turns up in practice.
+
+The first thing to try is the Android device profile. The iOS registration request carries six fields and none of them says anything about consent, terms or age; the Android one carries `tos_version`, `education_screen_displayed` and `clicked_education_link`.
+
+```sh
+WA_OS=android wa registration --code 5571976034186
+```
+
+If that is refused too, the number has to go through the real app once, on a phone, before it can be registered here.
+
+> [!NOTE]
+> The `login` field in that reply is worth reading. Brazilian mobiles gained a ninth digit that WhatsApp never adopted, so `+5571976034186` is filed as `+557176034186`. whalibmob adopts the server's form automatically on a successful registration and saves the session under it — the digit difference is not itself the failure.
+
 ## Routing Registration Through a Proxy
 
 Registration is the part of the protocol most likely to be refused from a datacenter IP. If you are seeing security blocks or an undeterminable number status, route it through a SOCKS proxy — Tor, or a residential provider.

package/cli.js

@@ -833,6 +833,49 @@ function askLoginMethod(phone) {
   });
 }
 
+// Handlers for the two things a registration can stop and ask for.
+//
+// The server can answer a submitted code with a captcha, or with a demand for
+// the account's two-step PIN. Neither is something the library can work out, so
+// both come back to whoever is driving it — here, the person at the terminal.
+function registrationPrompts() {
+  const prompt = (question) => new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve(null);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(String(answer).trim()); });
+  });
+
+  return {
+    async solveCaptcha({ image, audio }) {
+      out('');
+      hr();
+      out('  WhatsApp is asking for a CAPTCHA before it will finish this registration.');
+      // Written out rather than described: it is a picture, and there is
+      // nothing useful to say about it in a terminal.
+      for (const [what, buf, ext] of [['image', image, 'png'], ['audio', audio, 'mp3']]) {
+        if (!buf || !buf.length) continue;
+        const file = path.join(os.tmpdir(), 'whalibmob-captcha-' + Date.now() + '.' + ext);
+        try {
+          fs.writeFileSync(file, buf);
+          out('  ' + what + ' saved to  ' + file + '  (' + buf.length + ' bytes)');
+        } catch (e) {
+          out('  could not save the ' + what + ': ' + e.message);
+        }
+      }
+      hr();
+      const answer = await prompt('  what does it say?  ');
+      return answer || null;
+    },
+
+    async twoFactorPin() {
+      out('');
+      out('  this number has two-step verification switched on');
+      const pin = await prompt('  six-digit PIN:  ');
+      return pin || null;
+    }
+  };
+}
+
 // Link as a companion device.
 //
 // Connect first, then ask for the code: the request rides on the encrypted
@@ -2021,7 +2064,7 @@ async function handleLine(line) {
           const file  = path.join(_sessDir, `${ph}.json`);
           const store = loadStore(file) || initAuthCreds(ph);
           out('verifying...');
-          const r = await verifyCode(store, code);
+          const r = await verifyCode(store, code, registrationPrompts());
           if (r && (r.status === 'ok' || r.status === 'sent' || r.status === 'verified')) {
             if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
             const finalStore = r.store || store;
@@ -2419,7 +2462,7 @@ async function main() {
       const store = loadStore(file) || initAuthCreds(ph);
       out('verifying code for +' + ph + '...');
       try {
-        const r = await verifyCode(store, code);
+        const r = await verifyCode(store, code, registrationPrompts());
         if (r && (r.status === 'ok' || r.status === 'sent' || r.status === 'verified')) {
           if (!fs.existsSync(_sessDir)) fs.mkdirSync(_sessDir, { recursive: true });
           const finalStore = r.store || store;

package/lib/Registration.js

@@ -6,6 +6,7 @@ const tls    = require('tls');
 const curveJs = require('curve25519-js');
 const { getDeviceConfig } = require('./DeviceConfig');
 const attestation = require('./Attestation');
+const { dbg: _whaDbg } = require('./logger');
 
 // ---------- SOCKS4 / SOCKS5 / Tor support ----------
 //
@@ -136,51 +137,144 @@ async function httpPostViaSocks(path, body, waVersion, proxyUrl, authHeader) {
     `Content-Length: ${Buffer.byteLength(body)}`
   ];
   if (authHeader) reqLines.push(`Authorization: ${authHeader}`);
-  // close, not keep-alive: the response is read by waiting for the server to
-  // end the stream. Asking it to keep the connection open means that never
-  // happens and the request hangs until something else times out.
+  // Asked for, but not relied on: the server answers and then keeps the
+  // connection open anyway. The response is finished by its own length, not by
+  // the socket closing.
   reqLines.push(`Connection: close`, '', body);
   const req = reqLines.join('\r\n');
 
   tlsSocket.write(req);
 
-  const chunks = [];
-  await new Promise((res, rej) => {
+  const { status, body: bodyBuf } = await readHttpResponse(tlsSocket, path);
+  const bodyStr = bodyBuf.toString('utf8');
+
+  if (status !== 200) throw new Error(`HTTP ${status} ${path}: ${bodyStr}`);
+  try { return JSON.parse(bodyStr); } catch (_) { return { raw: bodyStr }; }
+}
+
+// A response is over when its own length says so, not when the socket shuts.
+//
+// This is the part `https.request` does for you and a hand-rolled socket does
+// not. WhatsApp answers a registration request in well under a second and then
+// leaves the connection open — `Connection: close` in the request does not
+// change that. Waiting for end or close therefore waited for something that
+// never came, and every proxied registration died on the read timeout with the
+// reply already sitting in the buffer.
+//
+// So: parse as the bytes arrive, and stop at the end of the body — the byte
+// count in Content-Length, or the terminating zero-length chunk. end and close
+// stay as a fallback, for a reply that declares neither and can only be
+// delimited by the connection itself.
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+function readHttpResponse(socket, label, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let raw    = Buffer.alloc(0);
+    let done   = false;
+
     const timer = setTimeout(() => {
-      tlsSocket.destroy();
-      rej(new Error('SOCKS proxy timed out reading ' + path));
-    }, 30000);
-    const finish = (fn, arg) => { clearTimeout(timer); fn(arg); };
-    tlsSocket.on('data',  d  => chunks.push(d));
-    tlsSocket.on('end',   () => finish(res));
-    tlsSocket.on('close', () => finish(res));
-    tlsSocket.on('error', e  => finish(rej, e));
+      settle(reject, new Error('SOCKS proxy timed out reading ' + label));
+    }, timeoutMs || 30000);
+
+    function settle(fn, arg) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      socket.removeListener('data',  onData);
+      socket.removeListener('end',   onEnd);
+      socket.removeListener('close', onEnd);
+      socket.removeListener('error', onError);
+      socket.destroy();
+      fn(arg);
+    }
+
+    function onData(chunk) {
+      raw = raw.length ? Buffer.concat([raw, chunk]) : chunk;
+      if (raw.length > MAX_RESPONSE_BYTES) {
+        return settle(reject, new Error('response too large reading ' + label));
+      }
+      const parsed = parseHttpResponse(raw, false);
+      if (parsed) settle(resolve, parsed);
+    }
+
+    // The connection did close after all — then whatever arrived is the whole
+    // reply, even without a declared length.
+    function onEnd() {
+      const parsed = parseHttpResponse(raw, true);
+      if (parsed) return settle(resolve, parsed);
+      settle(reject, new Error('connection closed mid-response reading ' + label));
+    }
+
+    function onError(err) { settle(reject, err); }
+
+    socket.on('data',  onData);
+    socket.on('end',   onEnd);
+    socket.on('close', onEnd);
+    socket.on('error', onError);
   });
+}
 
-  const raw        = Buffer.concat(chunks);
-  const rawStr     = raw.toString('utf8');
-  const headerEnd  = rawStr.indexOf('\r\n\r\n');
-  const headerPart = rawStr.slice(0, headerEnd);
-  const httpStatus = parseInt(rawStr.split(' ')[1]);
-  let bodyStr      = rawStr.slice(headerEnd + 4);
-
-  // Handle chunked transfer encoding
-  if (/transfer-encoding:\s*chunked/i.test(headerPart)) {
-    let decoded = '';
-    let pos = 0;
-    while (pos < bodyStr.length) {
-      const lineEnd = bodyStr.indexOf('\r\n', pos);
-      if (lineEnd === -1) break;
-      const chunkSize = parseInt(bodyStr.slice(pos, lineEnd), 16);
-      if (!chunkSize) break;
-      decoded += bodyStr.slice(lineEnd + 2, lineEnd + 2 + chunkSize);
-      pos = lineEnd + 2 + chunkSize + 2;
+/**
+ * Parse what has arrived so far.
+ *
+ * Returns { status, headers, body } once the response is complete, or null
+ * while it is still short. With `atEof` the caller is telling us no more bytes
+ * are coming, which is itself a valid way for a body to end.
+ */
+function parseHttpResponse(raw, atEof) {
+  const headerEnd = raw.indexOf('\r\n\r\n');
+  if (headerEnd < 0) return null;
+
+  // Headers are latin1 by definition; only the body may be UTF-8.
+  const headers   = raw.slice(0, headerEnd).toString('latin1');
+  const status    = parseInt(headers.split(' ')[1], 10);
+  const bodyStart = headerEnd + 4;
+
+  if (/^transfer-encoding:[ \t]*chunked/im.test(headers)) {
+    const decoded = decodeChunkedBody(raw.slice(bodyStart));
+    if (decoded) return { status, headers, body: decoded };
+    return atEof ? { status, headers, body: Buffer.alloc(0) } : null;
+  }
+
+  const match = /^content-length:[ \t]*(\d+)/im.exec(headers);
+  if (match) {
+    const length = parseInt(match[1], 10);
+    // Counted in bytes, which is why this works on the buffer and not on a
+    // decoded string — one accented character in an error message is two bytes
+    // and would leave the check one short forever.
+    if (raw.length - bodyStart >= length) {
+      return { status, headers, body: raw.slice(bodyStart, bodyStart + length) };
     }
-    bodyStr = decoded;
+    return atEof ? { status, headers, body: raw.slice(bodyStart) } : null;
   }
 
-  if (httpStatus !== 200) throw new Error(`HTTP ${httpStatus} ${path}: ${bodyStr}`);
-  try { return JSON.parse(bodyStr); } catch (_) { return { raw: bodyStr }; }
+  // These two carry no body at all, whatever else the headers say.
+  if (status === 204 || status === 304) {
+    return { status, headers, body: Buffer.alloc(0) };
+  }
+
+  // No length anywhere: the body runs to the end of the connection.
+  return atEof ? { status, headers, body: raw.slice(bodyStart) } : null;
+}
+
+/** Decode a chunked body, or null while the terminating chunk is still missing. */
+function decodeChunkedBody(buf) {
+  const parts = [];
+  let pos = 0;
+
+  for (;;) {
+    const lineEnd = buf.indexOf('\r\n', pos);
+    if (lineEnd < 0) return null;
+    // A size line may carry extensions after a semicolon; parseInt stops there.
+    const size = parseInt(buf.slice(pos, lineEnd).toString('latin1'), 16);
+    if (!Number.isFinite(size) || size < 0) return null;
+    if (size === 0) return Buffer.concat(parts);      // the terminating chunk
+    const start = lineEnd + 2;
+    const end   = start + size;
+    if (buf.length < end + 2) return null;            // chunk still arriving
+    parts.push(buf.slice(start, end));
+    pos = end + 2;
+  }
 }
 const {
   REGISTRATION_ENDPOINT,
@@ -651,6 +745,18 @@ function httpPost(path, body, waVersion, authHeader) {
 
 async function sendRequest(path, store, waVersion, useToken, extraPairs) {
   const plaintext = await buildPayload(store, waVersion, useToken, extraPairs);
+  return sendEncrypted(path, plaintext, store, waVersion);
+}
+
+/**
+ * Encrypt an already-built form body and post it.
+ *
+ * The attested endpoints reach this through sendRequest, which assembles the
+ * shared registration fields first. The funnel endpoints build their own much
+ * shorter body and come straight here — the native client sends no registration
+ * fields with a client log, only the identifiers and the screen names.
+ */
+async function sendEncrypted(path, plaintext, store, waVersion) {
   const enc  = encryptPayload(plaintext);   // base64url ENC payload (no prefix)
   let   body = 'ENC=' + enc;
 
@@ -667,6 +773,243 @@ async function sendRequest(path, store, waVersion, useToken, extraPairs) {
   return httpPost(path, body, waVersion, bodyAtt.authorizationHeader);
 }
 
+// ---------- Funnel telemetry ----------
+//
+// The native client reports every screen it moves through — the number entry,
+// the code request, the code submission, a captcha appearing, a PIN prompt —
+// to /client_log, and one session-start event to /pre_pn_client_log before the
+// number is even known. A client that registers without any of that is doing
+// something no real installation does.
+//
+// It is fire-and-forget by design. Every failure is swallowed: telemetry that
+// can abort a registration is worse than no telemetry. Set WA_FUNNEL_LOG=0 to
+// send none of it.
+
+function funnelEnabled() {
+  return process.env.WA_FUNNEL_LOG !== '0';
+}
+
+// The screen a verification event belongs to, named after the method that was
+// asked for — verify_sms, verify_voice. Before any request there is only the
+// number entry screen.
+function currentVerifyScreen(store) {
+  return store._lastRequestedMethod ? 'verify_' + store._lastRequestedMethod : 'enter_number';
+}
+
+async function sendFunnelLog(store, waVersion, currentScreen, actionTaken, eventName) {
+  if (!funnelEnabled()) return;
+  try {
+    const { cc, national } = parsePhone(store.phoneNumber);
+    const device = store.device || getDeviceConfig();
+    const fdid   = device.os === 'android'
+      ? store.fdid.toLowerCase()
+      : store.fdid.toUpperCase();
+
+    const body = buildForm([
+      'cc',              cc,
+      'in',              national,
+      'lg',              'en',
+      'lc',              'US',
+      'expid',           toBase64Url(store.deviceId),
+      'fdid',            fdid,
+      'id',              toUrlHex(store.identityId),
+      'current_screen',  currentScreen,
+      'previous_screen', store._funnelPreviousScreen || '',
+      'action_taken',    actionTaken,
+      'event_name',      eventName
+    ], null);
+
+    await sendEncrypted('/client_log', body, store, waVersion);
+    store._funnelPreviousScreen = currentScreen;
+  } catch (err) {
+    _whaDbg('[DBG] REG funnel log failed (' + currentScreen + '/' + actionTaken + '): ' +
+      (err && err.message));
+  }
+}
+
+// The one event that fires before a phone number is committed, so it carries
+// neither cc nor in.
+async function sendPrePnFunnelLog(store, waVersion, actionTaken, eventName) {
+  if (!funnelEnabled()) return;
+  try {
+    const device = store.device || getDeviceConfig();
+    const fdid   = device.os === 'android'
+      ? store.fdid.toLowerCase()
+      : store.fdid.toUpperCase();
+
+    const body = buildForm([
+      'lg',              'en',
+      'lc',              'US',
+      'expid',           toBase64Url(store.deviceId),
+      'fdid',            fdid,
+      'id',              toUrlHex(store.identityId),
+      'current_screen',  'enter_number',
+      'previous_screen', '',
+      'action_taken',    actionTaken,
+      'event_name',      eventName
+    ], null);
+
+    await sendEncrypted('/pre_pn_client_log', body, store, waVersion);
+  } catch (err) {
+    _whaDbg('[DBG] REG pre-pn funnel log failed: ' + (err && err.message));
+  }
+}
+
+// ---------- Challenge and two-factor ----------
+
+/** A captcha is a reply carrying an image or an audio blob to be solved. */
+function hasChallenge(response) {
+  if (!response) return false;
+  return !!((response.image_blob && String(response.image_blob).length) ||
+            (response.audio_blob && String(response.audio_blob).length));
+}
+
+/** Three spellings of the same demand, all of them still in use. */
+function is2FARequired(response) {
+  const reason = response && response.reason;
+  if (!reason) return false;
+  const r = String(reason).toLowerCase();
+  return r === '2fa_required' || r === 'security_code' || r === 'two_factor_required';
+}
+
+/**
+ * Decode a blob defensively.
+ *
+ * The server has been seen to switch between the standard and URL-safe base64
+ * alphabets between releases, so both are tried before giving up.
+ */
+function decodeOrNull(b64) {
+  if (!b64) return null;
+  const str = String(b64);
+  if (!str.length) return null;
+  for (const alphabet of ['base64', 'base64url']) {
+    try {
+      const out = Buffer.from(str, alphabet);
+      if (out.length) return out;
+    } catch (_) {}
+  }
+  return null;
+}
+
+function isSuccessful(status) {
+  return status === 'ok' || status === 'sent' || status === 'verified';
+}
+
+function normalizeCodeResult(code) {
+  return String(code == null ? '' : code).replace(/[\s\-]/g, '').replace(/\D/g, '');
+}
+
+// Take the digits the server filed the account under. Brazilian mobiles are the
+// standing example: they gained a ninth digit WhatsApp never adopted, and a
+// session saved under the typed number sends a username on every connection
+// that matches no registration.
+function adoptCanonicalNumber(store, result) {
+  const canonical = result.login ? String(result.login).replace(/\D/g, '') : null;
+  if (canonical && canonical !== String(store.phoneNumber)) {
+    result.canonicalPhoneNumber = canonical;
+    result.typedPhoneNumber     = String(store.phoneNumber);
+    store.phoneNumber           = canonical;
+  }
+  return result;
+}
+
+/**
+ * Answer a captcha, and keep answering while the server keeps asking.
+ *
+ * A wrong answer is replied to with another challenge rather than a refusal,
+ * which is why this loops. Solving needs a caller that can show the image to
+ * somebody: without one there is nothing to do but say so, and hand the blobs
+ * over on the error so it can be dealt with elsewhere.
+ */
+async function handleChallenge(store, waVersion, initial, opts) {
+  const screen = currentVerifyScreen(store);
+  await sendFunnelLog(store, waVersion, screen, 'challenge_shown', 'captcha_shown');
+
+  let response = initial;
+  for (;;) {
+    const image = decodeOrNull(response.image_blob);
+    const audio = decodeOrNull(response.audio_blob);
+
+    let answer = null;
+    if (typeof opts.solveCaptcha === 'function') {
+      answer = await opts.solveCaptcha({ image, audio, response });
+    }
+    if (!answer) {
+      await sendFunnelLog(store, waVersion, screen, 'challenge_abandoned', 'captcha_abandoned');
+      const err = new Error(
+        'Registration needs a CAPTCHA solved' +
+        (typeof opts.solveCaptcha === 'function'
+          ? ', and the solveCaptcha handler returned nothing.'
+          : ', and no solveCaptcha handler was given.\n' +
+            '  Pass one to verifyCode: verifyCode(store, code, { solveCaptcha: async ({ image, audio }) => "…" }).\n' +
+            '  image and audio are Buffers, or null when that variant was not sent.')
+      );
+      err.captcha = { image, audio };
+      err.raw     = response;
+      throw err;
+    }
+
+    await sendFunnelLog(store, waVersion, screen, 'challenge_submitted', 'captcha_submitted');
+    response = await sendRequest('/challenge', store, waVersion, true,
+      ['code', normalizeCodeResult(answer)]);
+
+    if (isSuccessful(response.status)) {
+      await sendFunnelLog(store, waVersion, 'account_verification_complete',
+        'challenge_submitted', 'captcha_success');
+      return adoptCanonicalNumber(store, response);
+    }
+    if (hasChallenge(response)) {
+      await sendFunnelLog(store, waVersion, screen, 'challenge_retry', 'captcha_retry');
+      continue;                                   // wrong answer, another one
+    }
+    if (is2FARequired(response)) return handle2FA(store, waVersion, opts);
+
+    const err = new Error('Registration CAPTCHA refused: ' +
+      (response.reason || response.status || JSON.stringify(response)));
+    err.raw = response;
+    throw err;
+  }
+}
+
+/**
+ * Supply the two-step verification PIN the account has set.
+ *
+ * This is the account owner's own PIN, not anything the library can work out —
+ * without a handler to ask, the registration stops here.
+ */
+async function handle2FA(store, waVersion, opts) {
+  await sendFunnelLog(store, waVersion, 'verify_twofac', 'twofac_shown', 'twofac_prompt_shown');
+
+  let pin = null;
+  if (typeof opts.twoFactorPin === 'function') pin = await opts.twoFactorPin();
+  if (!pin) {
+    await sendFunnelLog(store, waVersion, 'verify_twofac', 'twofac_abandoned', 'twofac_abandoned');
+    throw new Error(
+      'This number has two-step verification switched on and the registration ' +
+      'needs its PIN' +
+      (typeof opts.twoFactorPin === 'function'
+        ? ', but the twoFactorPin handler returned nothing.'
+        : '.\n  Pass one to verifyCode: verifyCode(store, code, { twoFactorPin: async () => "123456" }).\n' +
+          '  It is the six-digit PIN set on the phone under Settings → Account → Two-step verification.')
+    );
+  }
+
+  await sendFunnelLog(store, waVersion, 'verify_twofac', 'twofac_submitted', 'twofac_submitted');
+  const response = await sendRequest('/security', store, waVersion, true,
+    ['code', normalizeCodeResult(pin)]);
+
+  if (isSuccessful(response.status)) {
+    await sendFunnelLog(store, waVersion, 'account_verification_complete',
+      'twofac_submitted', 'twofac_success');
+    return adoptCanonicalNumber(store, response);
+  }
+
+  const err = new Error('Two-step verification PIN refused: ' +
+    (response.reason || response.status || JSON.stringify(response)));
+  err.raw = response;
+  throw err;
+}
+
 // ---------- Public API ----------
 
 async function checkIfRegistered(store) {
@@ -778,18 +1121,30 @@ async function checkNumberStatus(phoneNumber) {
 // Returns true  → keys are fresh (safe to proceed with /code).
 // Returns false → keys already registered (generate new store before /code).
 async function assertRegistrationKeys(store, waVersion) {
+  // The session-start event the native client fires before it knows the number.
+  await sendPrePnFunnelLog(store, waVersion, 'session_start', 'registration_session_start');
+  await sendFunnelLog(store, waVersion, 'enter_number', 'exist_check', 'exist_attempt');
+
   for (let attempt = 0; attempt < 2; attempt++) {
     try {
       const result = await sendRequest('/exist', store, waVersion, false, null);
       // reason === 'incorrect' → keys not found → fresh
-      if (result && result.reason === 'incorrect') return true;
+      if (result && result.reason === 'incorrect') {
+        await sendFunnelLog(store, waVersion, 'enter_number', 'exist_check', 'exist_success');
+        return true;
+      }
       // Any non-ok status on 2nd attempt → still treat as fresh (network/server glitch)
-      if (attempt === 1 && result && result.status && result.status !== 'ok') return true;
+      if (attempt === 1 && result && result.status && result.status !== 'ok') {
+        await sendFunnelLog(store, waVersion, 'enter_number', 'exist_check', 'exist_success');
+        return true;
+      }
     } catch (_) {
       // Network error = treat keys as fresh
       return true;
     }
   }
+
+  await sendFunnelLog(store, waVersion, 'enter_number', 'exist_check', 'exist_failure');
   return false;
 }
 
@@ -843,10 +1198,20 @@ async function requestSmsCode(store, method, opts) {
     while (true) {
       // Rebuilt per attempt so client_metrics carries the current attempt count.
       const extra = getRequestVerificationCodeParameters(store, m, _regMeta, _device, attemptNum);
+
+      // The screen a later event belongs to is named after the method asked
+      // for here, so record it before the request rather than after.
+      store._lastRequestedMethod = m;
+      const verifyScreen = currentVerifyScreen(store);
+      await sendFunnelLog(store, waVersion, verifyScreen, 'request_code', 'request_code_attempt');
+
       const result = await sendRequest('/code', store, waVersion, true, extra);
 
       const status = result.status;
-      if (status === 'ok' || status === 'sent') return result;
+      if (status === 'ok' || status === 'sent') {
+        await sendFunnelLog(store, waVersion, verifyScreen, 'request_code', 'request_code_success');
+        return result;
+      }
 
       const reason = result.reason || status || '';
 
@@ -903,16 +1268,23 @@ async function requestSmsCode(store, method, opts) {
   return result;
 }
 
-async function verifyCode(store, code) {
+async function verifyCode(store, code, opts) {
+  opts = opts || {};
   const _device   = getDeviceConfig();
   const waVersion = await fetchWaVersion(_device);
   store.version = waVersion;
   store.device  = _device;
   const normalized = code.replace(/[\s\-]/g, '').replace(/\D/g, '');
+
+  const screen = currentVerifyScreen(store);
+  await sendFunnelLog(store, waVersion, screen, 'submit_code', 'submit_code_attempt');
+
   const result = await sendRequest('/register', store, waVersion, true, ['code', normalized]);
 
   const status = result.status;
   if (status === 'ok' || status === 'sent' || status === 'verified') {
+    await sendFunnelLog(store, waVersion, 'account_verification_complete',
+      'submit_code', 'submit_code_success');
     // Adopt the number in the server's own form.
     //
     // WhatsApp answers with `login`, the canonical digits it filed the account
@@ -921,15 +1293,16 @@ async function verifyCode(store, code) {
     // under the eight-digit form, and a session saved under the typed number
     // sends a username on every connection that matches no registration. The
     // handshake then fails with 401 and nothing in the message hints at why.
-    const canonical = result.login ? String(result.login).replace(/\D/g, '') : null;
-    if (canonical && canonical !== String(store.phoneNumber)) {
-      result.canonicalPhoneNumber = canonical;
-      result.typedPhoneNumber     = String(store.phoneNumber);
-      store.phoneNumber           = canonical;
-    }
-    return result;
+    return adoptCanonicalNumber(store, result);
   }
 
+  // Before reading the reason, because neither of these arrives as one. A
+  // captcha comes as image and audio blobs with nothing else to go on, and a
+  // PIN demand names a reason that none of the branches below would match —
+  // both would otherwise fall through to the generic failure.
+  if (hasChallenge(result))  return handleChallenge(store, waVersion, result, opts);
+  if (is2FARequired(result)) return handle2FA(store, waVersion, opts);
+
   const reason = result.reason || '';
   if (reason === 'missing') {
     throw new Error(
@@ -943,13 +1316,56 @@ async function verifyCode(store, code) {
   if (/too_many/.test(reason)) {
     throw new Error('Verification failed: too many wrong attempts. Wait a few minutes then request a new code.');
   }
-  // Apple App Store age-verification / parental-consent gate.
-  // The code was accepted, but WhatsApp requires the Apple account holder to
-  // approve the app download before the registration can complete.
+  // Age / consent gate.
+  //
+  // The server found the account and did not complain about the code — it is
+  // asking for an age signal that only a real app-store install carries, and
+  // refusing to finish without it. Brazil is where this shows up, which fits:
+  // it is the market with an age-verification law behind it.
+  //
+  // Worth knowing before trying anything: the iOS request carries six fields
+  // and not one of them says anything about consent, terms or age. The Android
+  // one carries tos_version, education_screen_displayed and
+  // clicked_education_link. That is the difference to try first, and it costs
+  // nothing to try.
   if (result.pending === 'app_store_age' || reason === 'consent') {
-    return result;
+    const canonical = result.login ? String(result.login).replace(/\D/g, '') : null;
+    const lines = [
+      'Verification failed: WhatsApp wants an age-consent signal for this number ' +
+        'and will not finish the registration without one' +
+        (result.pending ? ' (pending: ' + result.pending + ')' : '') + '.',
+      '  The code itself was not refused — the account was found' +
+        (canonical ? ', filed as +' + canonical : '') + '.'
+    ];
+    if (canonical && canonical !== String(store.phoneNumber)) {
+      lines.push('  Note the digits: you typed +' + store.phoneNumber +
+        ', WhatsApp keeps it as +' + canonical + '. Brazilian mobiles gained a ' +
+        'ninth digit that WhatsApp did not adopt, and that alone is not the failure here.');
+    }
+    lines.push(
+      '  Try registering as an Android device instead — that request carries the ' +
+        'terms and education fields the iOS one has none of:',
+      '      WA_OS=android wa registration --code ' + store.phoneNumber,
+      '  If that is refused too, this number needs the real app once, on a phone, ' +
+        'to clear the gate.'
+    );
+    const err = new Error(lines.join('\n'));
+    err.reason    = reason;
+    err.pending   = result.pending || null;
+    err.canonicalPhoneNumber = canonical;
+    err.raw       = result;
+    throw err;
   }
   throw new Error(`Verification failed: ${reason || JSON.stringify(result)}`);
 }
 
 module.exports = { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, fetchIosVersion, fetchAndroidVersion, fetchWaVersion, parsePhone, getCountryMeta, assertRegistrationKeys, parseSocksProxy, socksProxyUrl };
+
+// The HTTP reader, exposed for tests. Not part of the public API.
+module.exports._http = { readHttpResponse, parseHttpResponse, decodeChunkedBody };
+
+// Challenge / two-factor internals, exposed for tests. Not part of the public API.
+module.exports._verify = {
+  hasChallenge, is2FARequired, decodeOrNull, isSuccessful,
+  normalizeCodeResult, currentVerifyScreen, adoptCanonicalNumber, funnelEnabled
+};

package/package.json

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