whalibmob 5.10.9 → 5.11.0

package/README.md

@@ -928,55 +928,65 @@ const {
 
 ### `makeCacheableSignalKeyStore`
 
-Wraps a `SignalStore` with an in-memory NodeCache layer (5-minute TTL). All `get` calls for `sessions`, `preKeys`, `signedPreKeys`, and `identities` are served from cache on subsequent accesses. Writes invalidate the cache automatically.
+Wraps a `SignalStore` with an in-memory cache (5-minute TTL). Reads for sessions, pre-keys, signed pre-keys and identity keys are served from cache on subsequent accesses; `store*` calls write through to both, and `remove*` / `delete*` calls drop the entry.
+
+A lookup that finds nothing is **not** cached. Absence is the state most likely to change from underneath — a session about to be built, a pre-key about to be uploaded — so a remembered miss is the one that would hurt.
 
 `useClones` is set to `false` so that `SessionRecord` objects — which carry internal state and methods — are returned by reference and never deep-cloned.
 
-The wrapper also forwards `transaction()` and `isInTransaction()` calls to the underlying store when present, making it safe to stack with `addTransactionCapability`.
+Every method the underlying store has is forwarded, including `transaction()` and `isInTransaction()` when present, so the wrapper is a drop-in replacement and safe to stack with `addTransactionCapability`.
 
 ```js
-const { SignalStore } = require('whalibmob')
-const { makeCacheableSignalKeyStore } = require('whalibmob')
+const { SignalStore, makeCacheableSignalKeyStore } = require('whalibmob')
 
-const store  = new SignalStore(/* ... */)
+const store  = new SignalStore()
 const cached = makeCacheableSignalKeyStore(store)
 
 // reads hit cache after first access
-const session = await cached.getSession('919634847671@s.whatsapp.net:0')
+const session = await cached.loadSession('919634847671.0')
 ```
 
+Call `await cached.flushCache()` to drop everything — after a key rotation, or when another process may have written to the same session file.
+
 **When to use:** whenever your `SignalStore` is backed by a remote or disk-based store (database, Redis, file system) and you want to reduce repeated lookups for sessions that haven't changed between sends.
 
 ### `addTransactionCapability`
 
-Wraps a `SignalStore` with batched-write (transaction) semantics. During a transaction all writes are buffered in memory; they are flushed to the underlying store atomically when `commit()` is called at the end of the transaction.
+Wraps a `SignalStore` with batched-write (transaction) semantics. During a transaction all writes are buffered in memory and flushed to the underlying store in one shot when the callback returns — there is no `commit()` to call. Reads check the buffer first, so a transaction sees its own writes. If the callback throws, nothing is written at all and the error reaches the caller.
 
-Uses `AsyncLocalStorage` to propagate transaction context across async call chains, and a per-key-type `Mutex` with reference-counting to serialize concurrent writers safely.
+Uses `AsyncLocalStorage` to propagate transaction context across async call chains, and a `Mutex` with reference-counting per transaction key.
 
 ```js
-const { addTransactionCapability, makeCacheableSignalKeyStore } = require('whalibmob')
+const { SignalStore, addTransactionCapability, makeCacheableSignalKeyStore } = require('whalibmob')
 
 // recommended: cache first, then transactions on top
-const base        = new SignalStore(/* ... */)
-const cached      = makeCacheableSignalKeyStore(base)
-const txnStore    = addTransactionCapability(cached)
+const base     = new SignalStore()
+const cached   = makeCacheableSignalKeyStore(base)
+const txnStore = addTransactionCapability(cached)
 
 // inside a send flow
 await txnStore.transaction(async () => {
-  // all writes are buffered
-  await txnStore.setSession('919634847671@s.whatsapp.net:0', sessionRecord)
-  await txnStore.setPreKey(1, preKeyPair)
-  // commit is called automatically at the end of the transaction callback
-})
+  // all writes are buffered until this callback returns
+  await txnStore.storeSession('919634847671.0', sessionRecord)
+  await txnStore.storePreKey(1, preKeyPair)
+}, 'send')
 ```
 
-Stacking order matters: put `makeCacheableSignalKeyStore` below `addTransactionCapability` so that the cache always sees the committed state.
+The second argument is a scope: two transactions with different keys run concurrently, two with the same key run one after the other. It defaults to `'default'`. Any key is safe — the transaction locks are kept separate from the locks reads take, so no choice of key can make a transaction wait on itself.
+
+Nested `transaction()` calls reuse the enclosing context instead of opening a second one, so an inner transaction does not commit on its own.
+
+Stacking order matters: put `makeCacheableSignalKeyStore` below `addTransactionCapability`, so that a transaction which rolls back never reaches the cache. The other order works too — a failed transaction flushes the cache rather than leave it holding writes the store never took — but it throws away good entries to do it.
 
 **When to use:** for high-throughput servers that send to many recipients concurrently and need to batch Signal key writes into a single atomic flush per message.
 
 ### `assertMeId`
 
-Validates that a store object has a registered phone number and returns the canonical `@s.whatsapp.net` JID. Throws an `Error` if the store lacks a `phoneNumber` or has `registered !== true`.
+Returns the account's JID, or throws an `Error` describing what is missing.
+
+Works with both kinds of store — the SMS store from `initAuthCreds` / `createNewStore`, and the companion store from `createNewWebStore`. Only the wording of the error differs, since the way out of "not registered yet" is SMS verification in one case and pairing in the other.
+
+Once registered, the JID the server assigned is preferred (`store.me.id`) — on a companion it carries the device suffix, and rebuilding it from the phone number drops that silently. Before registration it throws, including during the pairing window: requesting a pairing code writes a placeholder `me` with no suffix, and that is not treated as being linked.
 
 ```js
 const { assertMeId } = require('whalibmob')
@@ -985,7 +995,8 @@ const store = loadStore(sessFile)
 
 try {
   const jid = assertMeId(store)
-  // jid === '919634847671@s.whatsapp.net'
+  // '919634847671:12@s.whatsapp.net' once connected,
+  // '919634847671@s.whatsapp.net' before that
   console.log('account JID:', jid)
 } catch (err) {
   console.error('store is not registered:', err.message)
@@ -996,7 +1007,9 @@ try {
 
 ### `initAuthCreds`
 
-Creates a fresh credential store for the given phone number. Functionally equivalent to `createNewStore` but also initialises the extra fields the library expects for account sync: `nextPreKeyId`, `firstUnuploadedPreKeyId`, `accountSyncCounter`, `accountSettings`, and `advSecretKey`.
+Creates a fresh credential store for the given phone number — the key pairs, registration ID and device identifiers a number needs before it can even ask for an SMS code. This is what `/reg code` calls.
+
+It returns everything `createNewStore` does, plus a few fields kept for application code that expects them: `nextPreKeyId`, `firstUnuploadedPreKeyId`, `accountSyncCounter`, `accountSettings`, `processedHistoryMessages` and `advSecretKey`. Those extras live on the object only — `saveStore` does not write them, so they are not there again after a reload. Nothing in the library reads them; treat them as a convenience, not as state.
 
 ```js
 const { initAuthCreds, saveStore } = require('whalibmob')
@@ -1013,10 +1026,35 @@ const store = initAuthCreds(phone)
 saveStore(store, sessFile)
 ```
 
-This is the function used internally by the CLI for all new session creation. Prefer it over `createNewStore` for forward compatibility.
+This is the function the CLI uses for every new SMS session. Prefer it over `createNewStore` for forward compatibility.
 
 > [!NOTE]
-> `initAuthCreds` and `createNewStore` produce equivalent stores for all current library operations. The additional fields from `initAuthCreds` are there for future-proofing and interoperability.
+> `initAuthCreds` and `createNewStore` produce equivalent stores for every current library operation, and identical files on disk. Use `createNewWebStore` instead when the device will be linked as a companion rather than registered by SMS — that one adds the pairing fields, and its own serialiser persists them.
+
+The file it writes has exactly these 16 keys:
+
+```json
+{
+  "phoneNumber": "40712345678",
+  "noiseKeyPair":    { "private": "…", "public": "…" },
+  "identityKeyPair": { "private": "…", "public": "…" },
+  "signedPreKey":    { "id": 3649616, "private": "…", "public": "…", "signature": "…" },
+  "registrationId": 2183,
+  "fdid": "2f701f8b-d693-4728-…",
+  "deviceId": "CBIyyJRAokOdYoTYEjTbng==",
+  "identityId": "SE8Q785oful7dGdBgNpwjg==",
+  "advertisingId": "5c97eea9-783f-4fcc-…",
+  "backupToken": "…",
+  "registered": true,
+  "codePending": false,
+  "name": "Boss",
+  "version": "2.26.9.75",
+  "device": { "os": "ios", "platform": 1, "model": "iPhone 15 Pro", "…": "…" },
+  "advIdentity": "…"
+}
+```
+
+`registered` and `codePending` are the two that move: both `false` when the store is created, `codePending` flips to `true` once a code has been requested, and `verifyCode` sets `registered` to `true` and `codePending` back to `false`. `advIdentity` stays `null` until the server sends the signed device identity in `<success>`.
 
 ### Recommended Stacking Pattern
 
@@ -1036,7 +1074,8 @@ const {
 let store = loadStore(sessFile) || initAuthCreds(phone)
 
 // 2. build the layered Signal key store
-const signalStore = new SignalStore(store)
+const signalStore = new SignalStore()
+signalStore.attachFile(sessFile)
 const cachedStore = makeCacheableSignalKeyStore(signalStore)
 const txnStore    = addTransactionCapability(cachedStore)
 

package/lib/Client.js

@@ -1968,17 +1968,31 @@ class WhalibmobClient extends EventEmitter {
     const id    = String(attrs.id    || '');
     const ts    = parseInt(attrs.t || '0', 10);
     const participant = String(attrs.participant || from);
-    const senderPn = attrs.sender_pn ? String(attrs.sender_pn) : null;
-    if (senderPn) {
-      const lidUser = from.split('@')[0].split(':')[0];
-      const pnUser  = senderPn.split('@')[0].split(':')[0];
-      if (lidUser && pnUser && lidUser !== pnUser) {
-        this._lidToPn.set(lidUser, pnUser);
-        this._pnToLid.set(pnUser, lidUser);
-        // Persist so the mapping survives reconnects / process restarts
-        if (this._signal && this._signal.store && this._signal.store.setLidMapping) {
-          this._signal.store.setLidMapping(pnUser, lidUser);
-        }
+    const senderPn  = attrs.sender_pn  ? String(attrs.sender_pn)  : null;
+    const senderLid = attrs.sender_lid ? String(attrs.sender_lid) : null;
+
+    // Learn the LID ↔ phone pairing from whichever side the stanza names.
+    //
+    // Decryption needs it: a message addressed by LID has to be able to find a
+    // session filed under the phone JID, and the other way round. The pairing
+    // is only ever visible on a stanza that carries both names, so every such
+    // stanza is worth reading — sender_pn against a LID `from`, and sender_lid
+    // against a phone one.
+    const fromUser = from.split('@')[0].split(':')[0];
+    let learnedLid = null, learnedPn = null;
+    if (senderPn && from.endsWith('@lid')) {
+      learnedLid = fromUser;
+      learnedPn  = senderPn.split('@')[0].split(':')[0];
+    } else if (senderLid && !from.endsWith('@lid')) {
+      learnedPn  = fromUser;
+      learnedLid = senderLid.split('@')[0].split(':')[0];
+    }
+    if (learnedLid && learnedPn && learnedLid !== learnedPn) {
+      this._lidToPn.set(learnedLid, learnedPn);
+      this._pnToLid.set(learnedPn, learnedLid);
+      // Persist so the mapping survives reconnects / process restarts
+      if (this._signal && this._signal.store && this._signal.store.setLidMapping) {
+        this._signal.store.setLidMapping(learnedPn, learnedLid);
       }
     }
     _whaDbg('[DBG] _handleMessage from=' + from + ' participant=' + participant + ' senderPn=' + senderPn + ' id=' + id);
@@ -2050,21 +2064,107 @@ class WhalibmobClient extends EventEmitter {
     this._sendReadReceipt(id, fromRaw, partRaw);
   }
 
+  // The other name this contact answers to, with the device kept.
+  //
+  // A Signal address is user plus device, so the device has to survive the
+  // translation — 250139683860650:5@lid and 40752248147:5@s.whatsapp.net are
+  // the same device, 40752248147:0 is a different one.
+  //
+  // Returns null when there is no mapping for this user yet.
+  _counterpartJid(jid) {
+    if (!jid) return null;
+    const str  = String(jid);
+    const user = str.split('@')[0].split(':')[0];
+    if (!user) return null;
+    const colon  = str.split('@')[0].indexOf(':');
+    const device = colon >= 0 ? str.split('@')[0].slice(colon) : '';
+
+    if (str.endsWith('@lid')) {
+      const pn = this._lidToPn && this._lidToPn.get(user);
+      return pn ? pn + device + '@s.whatsapp.net' : null;
+    }
+    const lid = this._pnToLid && this._pnToLid.get(user);
+    return lid ? lid + device + '@lid' : null;
+  }
+
+  // Every address this message's session might be filed under, best first.
+  _signalJidCandidates(from, participant, senderPn) {
+    const out = [];
+    const add = (jid) => {
+      if (!jid) return;
+      const str = String(jid);
+      if (str && !out.includes(str)) out.push(str);
+    };
+
+    // Unchanged from before: the phone JID the stanza named, or the sender.
+    add(senderPn || ((participant && participant !== from) ? participant : from));
+    // Then the other name for each of them.
+    add(this._counterpartJid(out[0]));
+    add(participant && participant !== from ? participant : null);
+    add(from);
+    add(this._counterpartJid(participant && participant !== from ? participant : from));
+
+    return out;
+  }
+
+  // Try each address in turn and return the first plaintext.
+  //
+  // A failed attempt leaves nothing behind — libsignal either returns the
+  // plaintext or throws, and it only commits the advanced session on success —
+  // so trying the second address after the first misses is safe. The error
+  // reported on total failure is the first one, which is the one about the
+  // address the message actually named.
+  async _decryptWithCandidates(candidates, encType, cipherBuf, id) {
+    let firstErr = null;
+
+    for (let i = 0; i < candidates.length; i++) {
+      try {
+        const plaintext = await this._signal.decrypt(candidates[i], encType, cipherBuf);
+        if (i > 0) {
+          _whaDbg('[DBG] DM_DECRYPT id=' + id + ' recovered under ' + candidates[i] +
+            ' after ' + candidates[0] + ' had no session');
+        }
+        return plaintext;
+      } catch (err) {
+        if (!firstErr) firstErr = err;
+        // Only a missing session is worth asking a different address about.
+        // A session that exists and refuses the ciphertext is a different
+        // problem, and the answer is a retry receipt, not another lookup.
+        if (!/no matching sessions|no session/i.test(String(err && err.message))) break;
+      }
+    }
+
+    throw firstErr || new Error('decrypt: no address to try');
+  }
+
   _decryptDMMessage({ node, from, participant, fromRaw, partRaw, senderPn, id, ts, dmEncNode }) {
     const encType   = dmEncNode.attrs && dmEncNode.attrs.type;
     const cipherBuf = Buffer.isBuffer(dmEncNode.content)
       ? dmEncNode.content
       : Buffer.from(dmEncNode.content || '');
 
-    // WhatsApp LID migration: `from` may be a LID (linked identity) instead of a real phone number
-    // not the phone-based JID. The Signal session is stored under the phone-based JID.
-    // Use sender_pn (phone JID) when available, otherwise fall back to participant/from.
-    const sigJid = senderPn
-      || ((participant && participant !== from) ? participant : from);
+    // The same contact is reachable under two names — a phone JID and a LID —
+    // and a Signal address keeps only the user and the device, never the
+    // domain. So 250139683860650:5@lid and 40752248147:5@s.whatsapp.net are
+    // two different addresses for one person, and a session filed under either
+    // one is invisible from the other.
+    //
+    // Which name a message arrives under is the server's choice and it varies
+    // between messages from the same device. When the session was built under
+    // the phone JID and the next message comes addressed by LID, the lookup
+    // finds nothing and decryption fails with "No matching sessions found for
+    // message" — while the very next message from the same contact decrypts.
+    //
+    // The stanza's own name is tried first, so nothing that already works
+    // changes. The counterpart follows, from the LID↔phone mapping we keep.
+    const candidates = this._signalJidCandidates(from, participant, senderPn);
+    const sigJid     = candidates[0];
 
-    _whaDbg('[DBG] DM_DECRYPT id=' + id + ' type=' + encType + ' sigJid=' + sigJid + ' cipherLen=' + cipherBuf.length);
+    _whaDbg('[DBG] DM_DECRYPT id=' + id + ' type=' + encType + ' sigJid=' + sigJid +
+      (candidates.length > 1 ? ' alts=' + candidates.slice(1).join(',') : '') +
+      ' cipherLen=' + cipherBuf.length);
 
-    this._signal.decrypt(sigJid, encType, cipherBuf)
+    this._decryptWithCandidates(candidates, encType, cipherBuf, id)
       .then(async plaintext => {
         this._resolveRetry(id);
         const decoded = this._decodeMsg(plaintext);