whalibmob 5.10.9 → 5.10.12

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/auth-utils.js

@@ -2,26 +2,31 @@
 
 // ─── auth-utils.js ────────────────────────────────────────────────────────────
 //
-// Four utilities built around whalibmob's architecture (method-based
-// SignalStore, Buffer key pairs, etc.):
+// Optional helpers for code that manages its own SignalStore — a custom storage
+// backend, a multi-account server, anything that wants caching or transactional
+// writes around the store the library would otherwise use directly.
 //
-//  1. makeCacheableSignalKeyStore  — wraps SignalStore with NodeCache (5-min TTL)
-//                                   and a Mutex for all read/write operations
-//  2. addTransactionCapability     — wraps SignalStore with transaction support
-//                                   backed by AsyncLocalStorage + per-type Mutex
-//  3. assertMeId                   — validates auth credentials, returns JID or throws
-//  4. initAuthCreds                — creates a fresh credential set for a phone number
+//  1. makeCacheableSignalKeyStore  — an in-memory cache with a 5-minute TTL in
+//                                    front of the store, serialised by a Mutex
+//  2. addTransactionCapability     — buffered writes committed in one shot,
+//                                    scoped with AsyncLocalStorage
+//  3. assertMeId                   — the account's JID, or a clear error
+//  4. initAuthCreds                — a fresh credential set for a phone number
 //
-// Usage example:
-//   const { SignalStore }                       = require('whalibmob');
+// Stacking order matters. The cache belongs *underneath* the transaction:
+//
+//   const { SignalStore } = require('whalibmob');
 //   const { makeCacheableSignalKeyStore,
-//           addTransactionCapability,
-//           assertMeId, initAuthCreds }         = require('whalibmob/lib/auth-utils');
+//           addTransactionCapability } = require('whalibmob/lib/auth-utils');
+//
+//   const raw    = new SignalStore();
+//   const cached = makeCacheableSignalKeyStore(raw, logger);
+//   const store  = addTransactionCapability(cached, logger);
 //
-//   const rawStore = new SignalStore();
-//   // Optionally stack both capabilities:
-//   const txStore     = addTransactionCapability(rawStore, logger, { maxCommitRetries: 5, delayBetweenTriesMs: 250 });
-//   const cachedStore = makeCacheableSignalKeyStore(txStore, logger);
+// That way a transaction that throws never reaches the cache at all — its
+// writes are still sitting in the transaction buffer when it is discarded. The
+// other order works too, and a rollback flushes the cache to stay honest, but
+// it throws away entries that were perfectly good.
 //
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -33,8 +38,14 @@ const { createNewStore }    = require('./Store');
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-/** In-memory TTL for Signal store cache entries (sessions, keys, identities). */
-const SIGNAL_STORE_TTL      = '5m';
+/**
+ * How long a cached entry lives, in seconds.
+ *
+ * The option is `stdTTL` and the unit is seconds — `ttl`, and a string like
+ * '5m', are both accepted without complaint and then ignored, which leaves a
+ * cache that never evicts anything and answers from it forever.
+ */
+const SIGNAL_STORE_TTL_SECONDS = 5 * 60;
 
 /** Default max retry count for transaction commits. */
 const MAX_COMMIT_RETRIES    = 5;
@@ -48,26 +59,63 @@ function _delay(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * Forward every method the wrapper did not define itself.
+ *
+ * Both wrappers claim to be drop-in replacements, and a hand-written list stops
+ * being one the moment the store grows a method — the call does not fail
+ * loudly, it lands on `undefined`. Anything the wrapper has an opinion about is
+ * already on it and is left alone; the rest is passed straight through.
+ */
+function _fillPassthrough(wrapper, store) {
+  const seen = new Set();
+  let level  = store;
+
+  while (level && level !== Object.prototype) {
+    for (const name of Object.getOwnPropertyNames(level)) {
+      if (seen.has(name) || name === 'constructor' || name.startsWith('_')) continue;
+      seen.add(name);
+      if (name in wrapper) continue;                  // the wrapper handles it
+      let fn;
+      try { fn = store[name]; } catch (_) { continue; }   // skip throwing getters
+      if (typeof fn !== 'function') continue;
+      wrapper[name] = (...args) => store[name](...args);
+    }
+    level = Object.getPrototypeOf(level);
+  }
+
+  return wrapper;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 //  1. makeCacheableSignalKeyStore
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Wraps a whalibmob SignalStore with:
- *   • NodeCache — in-memory cache with a 5-minute TTL for all key types
+ * Wraps a SignalStore with:
+ *   • NodeCache — an in-memory cache with a 5-minute TTL for every key type
  *     (sessions, pre-keys, signed pre-keys, identity keys, registration ID).
- *     After 5 minutes each entry is evicted and re-read from disk on the
- *     next access, keeping memory bounded without ever returning stale data.
- *   • Mutex  — every get/set is serialised through a single Mutex, preventing
- *     Signal session race conditions that would produce undecryptable ciphertexts.
+ *     Each entry is evicted after that and re-read on the next access, which
+ *     bounds memory and puts a ceiling on how long another writer's change can
+ *     go unnoticed.
+ *   • Mutex  — every get/set is serialised, so two concurrent operations cannot
+ *     interleave a read against a write to the same key.
+ *
+ * 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 — and a remembered miss is the one that hurts.
  *
  * @param {SignalStore}  store   - underlying SignalStore instance
  * @param {object}       logger  - optional logger with a .trace() method
- * @param {NodeCache}    _cache  - optional pre-built NodeCache (for testing / sharing)
+ * @param {NodeCache}    _cache  - optional pre-built cache (for testing / sharing)
  * @returns {object} drop-in SignalStore replacement with caching and serialisation
  */
 function makeCacheableSignalKeyStore(store, logger, _cache) {
-  const cache = _cache || new NodeCache({ ttl: SIGNAL_STORE_TTL, useClones: false });
+  const cache = _cache || new NodeCache({
+    stdTTL:         SIGNAL_STORE_TTL_SECONDS,
+    useClones:      false,
+    deleteOnExpire: true
+  });
   const mutex = new Mutex();
 
   /** Unified cache key: "type:id" */
@@ -75,8 +123,59 @@ function makeCacheableSignalKeyStore(store, logger, _cache) {
 
   const log = (msg, data) => logger && logger.trace(data, msg);
 
-  return {
-    // ── Initialisation / file attachment (pass-through) ──────────────────────
+  // Read through the cache, remembering only what was actually found.
+  function cachedRead(type, id, load) {
+    return mutex.runExclusive(async () => {
+      const k   = cKey(type, id);
+      const hit = cache.get(k);
+      if (hit !== undefined) {
+        log(type + ' cache hit', { id });
+        return hit;
+      }
+      const val = await load();
+      if (val !== undefined && val !== null) cache.set(k, val);
+      return val;
+    });
+  }
+
+  function cachedWrite(type, id, value, write) {
+    return mutex.runExclusive(async () => {
+      cache.set(cKey(type, id), value);
+      return write();
+    });
+  }
+
+  function cachedDelete(type, id, remove) {
+    return mutex.runExclusive(async () => {
+      cache.del(cKey(type, id));
+      return remove();
+    });
+  }
+
+  // Named rather than reached for through `this`, so a caller may pull a method
+  // off the object — `const { loadSession } = cachedStore` — and still call it.
+  async function getLocalRegistrationId() {
+    return mutex.runExclusive(async () => {
+      const hit = cache.get('meta:registrationId');
+      if (hit !== undefined) return hit;
+      const val = await store.getLocalRegistrationId();
+      if (val !== undefined && val !== null) cache.set('meta:registrationId', val);
+      return val;
+    });
+  }
+
+  async function identity(load) {
+    return mutex.runExclusive(async () => {
+      const hit = cache.get('meta:identityKeyPair');
+      if (hit !== undefined) return hit;
+      const val = await load();
+      if (val) cache.set('meta:identityKeyPair', val);
+      return val;
+    });
+  }
+
+  const wrapper = {
+    // ── Initialisation ───────────────────────────────────────────────────────
 
     init(identityKeyPair, registrationId) {
       cache.set('meta:identityKeyPair', identityKeyPair);
@@ -84,171 +183,83 @@ function makeCacheableSignalKeyStore(store, logger, _cache) {
       return store.init(identityKeyPair, registrationId);
     },
 
-    attachFile(filePath)             { return store.attachFile(filePath); },
-    setLidMapping(phone, lid)        { return store.setLidMapping(phone, lid); },
-    getLidMappings()                 { return store.getLidMappings(); },
-    preKeyCount()                    { return store.preKeyCount(); },
-    nextPreKeyId()                   { return store.nextPreKeyId(); },
-    /** Synchronous hasSession — never cached; always reads from in-memory sessions map. */
-    hasSession(encodedAddress)       { return store.hasSession(encodedAddress); },
+    /** Synchronous — never cached; reads the store's own in-memory session map. */
+    hasSession(encodedAddress) { return store.hasSession(encodedAddress); },
 
     // ── Identity / registration ───────────────────────────────────────────────
 
-    async getOurIdentity() {
-      return mutex.runExclusive(async () => {
-        const hit = cache.get('meta:identityKeyPair');
-        if (hit !== undefined) return hit;
-        const val = await store.getOurIdentity();
-        if (val) cache.set('meta:identityKeyPair', val);
-        return val;
-      });
-    },
+    getOurIdentity()         { return identity(() => store.getOurIdentity()); },
+    getIdentityKeyPair()     { return identity(() => store.getIdentityKeyPair()); },
+    getLocalRegistrationId,
+    getOurRegistrationId()   { return getLocalRegistrationId(); },
 
-    async getIdentityKeyPair() {
-      return mutex.runExclusive(async () => {
-        const hit = cache.get('meta:identityKeyPair');
-        if (hit !== undefined) return hit;
-        const val = await store.getIdentityKeyPair();
-        if (val) cache.set('meta:identityKeyPair', val);
-        return val;
-      });
-    },
-
-    async getLocalRegistrationId() {
-      return mutex.runExclusive(async () => {
-        const hit = cache.get('meta:registrationId');
-        if (hit !== undefined) return hit;
-        const val = await store.getLocalRegistrationId();
-        cache.set('meta:registrationId', val);
-        return val;
-      });
-    },
-
-    async getOurRegistrationId() {
-      return this.getLocalRegistrationId();
-    },
-
-    /** isTrustedIdentity — never cached; always delegates to underlying store. */
+    /** Never cached; the store decides trust from its own current state. */
     async isTrustedIdentity(identifier, identityKey) {
       return store.isTrustedIdentity(identifier, identityKey);
     },
 
-    async saveIdentity(identifier, identityKey) {
-      return mutex.runExclusive(async () => {
-        cache.del(cKey('identity', identifier));
-        return store.saveIdentity(identifier, identityKey);
-      });
+    saveIdentity(identifier, identityKey) {
+      return cachedDelete('identity', identifier,
+        () => store.saveIdentity(identifier, identityKey));
     },
 
-    async loadIdentityKey(identifier) {
-      return mutex.runExclusive(async () => {
-        const k   = cKey('identity', identifier);
-        const hit = cache.get(k);
-        if (hit !== undefined) {
-          log('identity cache hit', { identifier });
-          return hit;
-        }
-        const val = await store.loadIdentityKey(identifier);
-        cache.set(k, val !== null && val !== undefined ? val : null);
-        return val;
-      });
+    loadIdentityKey(identifier) {
+      return cachedRead('identity', identifier,
+        () => store.loadIdentityKey(identifier));
     },
 
-    // ── Sessions (hot path — every message send/receive touches these) ────────
+    // ── Sessions (hot path — every message send and receive touches these) ────
 
-    async loadSession(encodedAddress) {
-      return mutex.runExclusive(async () => {
-        const k   = cKey('session', encodedAddress);
-        const hit = cache.get(k);
-        if (hit !== undefined) {
-          log('session cache hit', { encodedAddress });
-          return hit;
-        }
-        const val = await store.loadSession(encodedAddress);
-        if (val) cache.set(k, val);
-        return val;
-      });
+    loadSession(encodedAddress) {
+      return cachedRead('session', encodedAddress,
+        () => store.loadSession(encodedAddress));
     },
 
-    async storeSession(encodedAddress, record) {
-      return mutex.runExclusive(async () => {
-        cache.set(cKey('session', encodedAddress), record);
-        return store.storeSession(encodedAddress, record);
-      });
+    storeSession(encodedAddress, record) {
+      return cachedWrite('session', encodedAddress, record,
+        () => store.storeSession(encodedAddress, record));
     },
 
-    async deleteSession(encodedAddress) {
-      return mutex.runExclusive(async () => {
-        cache.del(cKey('session', encodedAddress));
-        return store.deleteSession(encodedAddress);
-      });
+    deleteSession(encodedAddress) {
+      return cachedDelete('session', encodedAddress,
+        () => store.deleteSession(encodedAddress));
     },
 
     // ── Pre-keys ──────────────────────────────────────────────────────────────
 
-    async loadPreKey(keyId) {
-      return mutex.runExclusive(async () => {
-        const k   = cKey('prekey', keyId);
-        const hit = cache.get(k);
-        if (hit !== undefined) {
-          log('prekey cache hit', { keyId });
-          return hit;
-        }
-        const val = await store.loadPreKey(keyId);
-        if (val) cache.set(k, val);
-        return val;
-      });
+    loadPreKey(keyId) {
+      return cachedRead('prekey', keyId, () => store.loadPreKey(keyId));
     },
 
-    async storePreKey(keyId, keyPair) {
-      return mutex.runExclusive(async () => {
-        cache.set(cKey('prekey', keyId), keyPair);
-        return store.storePreKey(keyId, keyPair);
-      });
+    storePreKey(keyId, keyPair) {
+      return cachedWrite('prekey', keyId, keyPair,
+        () => store.storePreKey(keyId, keyPair));
     },
 
-    async removePreKey(keyId) {
-      return mutex.runExclusive(async () => {
-        cache.del(cKey('prekey', keyId));
-        return store.removePreKey(keyId);
-      });
+    removePreKey(keyId) {
+      return cachedDelete('prekey', keyId, () => store.removePreKey(keyId));
     },
 
     // ── Signed pre-keys ───────────────────────────────────────────────────────
 
-    async loadSignedPreKey(keyId) {
-      return mutex.runExclusive(async () => {
-        const k   = cKey('signedprekey', keyId);
-        const hit = cache.get(k);
-        if (hit !== undefined) {
-          log('signed-prekey cache hit', { keyId });
-          return hit;
-        }
-        const val = await store.loadSignedPreKey(keyId);
-        if (val) cache.set(k, val);
-        return val;
-      });
+    loadSignedPreKey(keyId) {
+      return cachedRead('signedprekey', keyId, () => store.loadSignedPreKey(keyId));
     },
 
-    async storeSignedPreKey(keyId, keyPair) {
-      return mutex.runExclusive(async () => {
-        cache.set(cKey('signedprekey', keyId), keyPair);
-        return store.storeSignedPreKey(keyId, keyPair);
-      });
+    storeSignedPreKey(keyId, keyPair) {
+      return cachedWrite('signedprekey', keyId, keyPair,
+        () => store.storeSignedPreKey(keyId, keyPair));
     },
 
-    async removeSignedPreKey(keyId) {
-      return mutex.runExclusive(async () => {
-        cache.del(cKey('signedprekey', keyId));
-        return store.removeSignedPreKey(keyId);
-      });
+    removeSignedPreKey(keyId) {
+      return cachedDelete('signedprekey', keyId, () => store.removeSignedPreKey(keyId));
     },
 
     // ── Transaction forwarding ────────────────────────────────────────────────
-    // If the underlying store was wrapped with addTransactionCapability, forward
-    // transaction() and isInTransaction() so stacking both wrappers works correctly.
+    // Present so the cache can sit on top of addTransactionCapability as well as
+    // underneath it, even though underneath is the better place for it.
 
-    /** Returns true if the current async context is inside a transaction. */
+    /** True when the current async context is inside a transaction. */
     isInTransaction() {
       return typeof store.isInTransaction === 'function'
         ? store.isInTransaction()
@@ -256,9 +267,12 @@ function makeCacheableSignalKeyStore(store, logger, _cache) {
     },
 
     /**
-     * Delegate to the underlying store's transaction() if available.
-     * This lets you stack makeCacheableSignalKeyStore on top of addTransactionCapability
-     * and still call .transaction() on the outermost wrapper.
+     * Delegate to the underlying store's transaction, dropping the cache if it
+     * does not go through.
+     *
+     * Writes reach the cache as they are made, but a transaction that throws
+     * never commits them — so without this the cache would keep serving values
+     * the store never took, and go on doing it until the entries expired.
      */
     transaction(work, key) {
       if (typeof store.transaction !== 'function') {
@@ -267,16 +281,27 @@ function makeCacheableSignalKeyStore(store, logger, _cache) {
           'with addTransactionCapability()'
         );
       }
-      return store.transaction(work, key);
+      return (async () => {
+        try {
+          return await store.transaction(work, key);
+        } catch (error) {
+          cache.flushAll();
+          logger && logger.trace('transaction failed — cache flushed');
+          throw error;
+        }
+      })();
     },
 
     // ── Cache control ─────────────────────────────────────────────────────────
 
-    /** Flush all cached entries (e.g. after a key rotation or re-registration). */
+    /** Drop every cached entry, here and in anything wrapped below. */
     async flushCache() {
       cache.flushAll();
+      if (typeof store.flushCache === 'function') await store.flushCache();
     }
   };
+
+  return _fillPassthrough(wrapper, store);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -284,16 +309,13 @@ function makeCacheableSignalKeyStore(store, logger, _cache) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Adds DB-like transaction capability to a whalibmob SignalStore.
+ * Adds DB-like transaction capability to a SignalStore.
  *
- * Within a transaction all writes are buffered in an in-memory context
- * (scoped via AsyncLocalStorage).  Reads check the buffer first so they see
- * their own writes.  On commit the buffer is flushed to the underlying store
- * in one shot with retry logic.  Nested transactions transparently reuse the
- * enclosing context — no double-commit.
- *
- * Per-type Mutex objects serialise concurrent reads against the underlying
- * store when multiple transactions are in flight simultaneously.
+ * Within a transaction all writes are buffered in an in-memory context (scoped
+ * with AsyncLocalStorage). Reads check the buffer first so they see their own
+ * writes. On commit the buffer is flushed to the underlying store in one shot,
+ * with retries. Nested transactions reuse the enclosing context, so there is no
+ * double commit.
  *
  * @param {SignalStore}  state   - underlying store (may already be cached)
  * @param {object}       logger  - optional logger with .trace() / .warn() / .error()
@@ -302,33 +324,47 @@ function makeCacheableSignalKeyStore(store, logger, _cache) {
  */
 function addTransactionCapability(state, logger, opts) {
   opts = opts || {};
-  const maxRetries  = opts.maxCommitRetries   ?? MAX_COMMIT_RETRIES;
+  const maxRetries  = opts.maxCommitRetries    ?? MAX_COMMIT_RETRIES;
   const retryDelay  = opts.delayBetweenTriesMs ?? RETRY_DELAY_MS;
 
-  const txStorage     = new AsyncLocalStorage();
-  const typeMutexes   = new Map();   // type → Mutex
-  const typeMutexRefs = new Map();   // type → refcount
+  const txStorage = new AsyncLocalStorage();
+
+  // Two separate sets of locks, and they must stay separate.
+  //
+  // A transaction holds its lock for as long as the work runs, and reads inside
+  // that work take a lock of their own. Sharing one map means transaction('…',
+  // 'session') takes the session lock and then waits for itself the first time
+  // it loads a session — a deadlock with no error and no timeout, reachable
+  // from nothing worse than an unlucky choice of key.
+  const readMutexes = new Map();   // data type → Mutex, held only for one read
+  const txMutexes   = new Map();   // transaction key → Mutex, held for the work
+  const txMutexRefs = new Map();   // transaction key → refcount
+
+  function getReadMutex(type) {
+    if (!readMutexes.has(type)) readMutexes.set(type, new Mutex());
+    return readMutexes.get(type);
+  }
 
-  function getMutex(type) {
-    if (!typeMutexes.has(type)) {
-      typeMutexes.set(type, new Mutex());
-      typeMutexRefs.set(type, 0);
+  function getTxMutex(key) {
+    if (!txMutexes.has(key)) {
+      txMutexes.set(key, new Mutex());
+      txMutexRefs.set(key, 0);
     }
-    return typeMutexes.get(type);
+    return txMutexes.get(key);
   }
 
-  function acquireRef(type) {
-    typeMutexRefs.set(type, (typeMutexRefs.get(type) ?? 0) + 1);
+  function acquireRef(key) {
+    txMutexRefs.set(key, (txMutexRefs.get(key) ?? 0) + 1);
   }
 
-  function releaseRef(type) {
-    const count = (typeMutexRefs.get(type) ?? 1) - 1;
-    typeMutexRefs.set(type, count);
+  function releaseRef(key) {
+    const count = (txMutexRefs.get(key) ?? 1) - 1;
+    txMutexRefs.set(key, count);
     if (count <= 0) {
-      const m = typeMutexes.get(type);
+      const m = txMutexes.get(key);
       if (m && !m.isLocked()) {
-        typeMutexes.delete(type);
-        typeMutexRefs.delete(type);
+        txMutexes.delete(key);
+        txMutexRefs.delete(key);
       }
     }
   }
@@ -340,7 +376,7 @@ function addTransactionCapability(state, logger, opts) {
   async function commitWithRetry(ctx) {
     const { sessions, preKeys, signedPreKeys, identities } = ctx.mutations;
     const total = (
-      Object.keys(sessions).length     +
+      Object.keys(sessions).length      +
       Object.keys(preKeys).length       +
       Object.keys(signedPreKeys).length +
       Object.keys(identities).length
@@ -357,33 +393,22 @@ function addTransactionCapability(state, logger, opts) {
         const proms = [];
 
         for (const [addr, rec] of Object.entries(sessions)) {
-          if (rec === null) {
-            proms.push(state.deleteSession(addr));
-          } else {
-            proms.push(state.storeSession(addr, rec));
-          }
+          proms.push(rec === null ? state.deleteSession(addr)
+                                  : state.storeSession(addr, rec));
         }
 
         for (const [keyId, kp] of Object.entries(preKeys)) {
-          if (kp === null) {
-            proms.push(state.removePreKey(Number(keyId)));
-          } else {
-            proms.push(state.storePreKey(Number(keyId), kp));
-          }
+          proms.push(kp === null ? state.removePreKey(Number(keyId))
+                                 : state.storePreKey(Number(keyId), kp));
         }
 
         for (const [keyId, kp] of Object.entries(signedPreKeys)) {
-          if (kp === null) {
-            proms.push(state.removeSignedPreKey(Number(keyId)));
-          } else {
-            proms.push(state.storeSignedPreKey(Number(keyId), kp));
-          }
+          proms.push(kp === null ? state.removeSignedPreKey(Number(keyId))
+                                 : state.storeSignedPreKey(Number(keyId), kp));
         }
 
         for (const [identifier, key] of Object.entries(identities)) {
-          if (key !== null) {
-            proms.push(state.saveIdentity(identifier, key));
-          }
+          if (key !== null) proms.push(state.saveIdentity(identifier, key));
         }
 
         await Promise.all(proms);
@@ -398,135 +423,101 @@ function addTransactionCapability(state, logger, opts) {
     }
   }
 
-  // Build the empty mutation / read-buffer context for a new transaction.
+  // The empty read buffer and pending writes for a new transaction.
   function makeCtx() {
     return {
-      // Read buffer: what we've already loaded from the underlying store
-      sessions:     {},
-      preKeys:      {},
-      signedPreKeys:{},
-      identities:   {},
-      // Pending writes: committed to disk on transaction end
+      // Read buffer: what has already been loaded from the underlying store
+      sessions:      {},
+      preKeys:       {},
+      signedPreKeys: {},
+      identities:    {},
+      // Pending writes: flushed to the store when the transaction ends
       mutations: {
-        sessions:     {},
-        preKeys:      {},
-        signedPreKeys:{},
-        identities:   {}
+        sessions:      {},
+        preKeys:       {},
+        signedPreKeys: {},
+        identities:    {}
       },
       dbQueries: 0
     };
   }
 
-  return {
-    // ── Pass-through non-transactional methods ────────────────────────────────
-    init(ikp, regId)             { return state.init(ikp, regId); },
-    attachFile(fp)               { return state.attachFile(fp); },
-    setLidMapping(phone, lid)    { return state.setLidMapping(phone, lid); },
-    getLidMappings()             { return state.getLidMappings(); },
-    preKeyCount()                { return state.preKeyCount(); },
-    nextPreKeyId()               { return state.nextPreKeyId(); },
-    hasSession(addr)             { return state.hasSession(addr); },
-    getOurIdentity()             { return state.getOurIdentity(); },
-    getIdentityKeyPair()         { return state.getIdentityKeyPair(); },
-    getLocalRegistrationId()     { return state.getLocalRegistrationId(); },
-    getOurRegistrationId()       { return state.getOurRegistrationId(); },
-    isTrustedIdentity(a, b)      { return state.isTrustedIdentity(a, b); },
+  // Read through the transaction buffer, or straight through when there is no
+  // transaction in this async context.
+  async function bufferedRead(bucket, type, id, load) {
+    const ctx = txStorage.getStore();
+    if (!ctx) return load();
+    const k = String(id);
+    if (k in ctx[bucket]) return ctx[bucket][k];
+    const val = await getReadMutex(type).runExclusive(load);
+    ctx[bucket][k] = val;
+    ctx.dbQueries++;
+    return val;
+  }
 
+  async function bufferedWrite(bucket, id, value, write) {
+    const ctx = txStorage.getStore();
+    if (!ctx) return write();
+    const k = String(id);
+    ctx[bucket][k] = value;
+    ctx.mutations[bucket][k] = value;
+  }
+
+  const wrapper = {
     // ── Session ───────────────────────────────────────────────────────────────
 
-    async loadSession(encodedAddress) {
-      const ctx = txStorage.getStore();
-      if (!ctx) return state.loadSession(encodedAddress);
-      if (encodedAddress in ctx.sessions) return ctx.sessions[encodedAddress];
-      // Not in buffer: fetch under mutex, cache in buffer
-      const val = await getMutex('session').runExclusive(() => state.loadSession(encodedAddress));
-      ctx.sessions[encodedAddress] = val;
-      ctx.dbQueries++;
-      return val;
+    loadSession(encodedAddress) {
+      return bufferedRead('sessions', 'session', encodedAddress,
+        () => state.loadSession(encodedAddress));
     },
 
-    async storeSession(encodedAddress, record) {
-      const ctx = txStorage.getStore();
-      if (!ctx) return state.storeSession(encodedAddress, record);
-      ctx.sessions[encodedAddress] = record;
-      ctx.mutations.sessions[encodedAddress] = record;
+    storeSession(encodedAddress, record) {
+      return bufferedWrite('sessions', encodedAddress, record,
+        () => state.storeSession(encodedAddress, record));
     },
 
-    async deleteSession(encodedAddress) {
-      const ctx = txStorage.getStore();
-      if (!ctx) return state.deleteSession(encodedAddress);
-      ctx.sessions[encodedAddress] = null;
-      ctx.mutations.sessions[encodedAddress] = null;
+    deleteSession(encodedAddress) {
+      return bufferedWrite('sessions', encodedAddress, null,
+        () => state.deleteSession(encodedAddress));
     },
 
     // ── Pre-keys ──────────────────────────────────────────────────────────────
 
-    async loadPreKey(keyId) {
-      const ctx = txStorage.getStore();
-      const k   = String(keyId);
-      if (!ctx) return state.loadPreKey(keyId);
-      if (k in ctx.preKeys) return ctx.preKeys[k];
-      const val = await getMutex('preKey').runExclusive(() => state.loadPreKey(keyId));
-      ctx.preKeys[k] = val;
-      ctx.dbQueries++;
-      return val;
+    loadPreKey(keyId) {
+      return bufferedRead('preKeys', 'preKey', keyId, () => state.loadPreKey(keyId));
     },
 
-    async storePreKey(keyId, keyPair) {
-      const ctx = txStorage.getStore();
-      const k   = String(keyId);
-      if (!ctx) return state.storePreKey(keyId, keyPair);
-      ctx.preKeys[k] = keyPair;
-      ctx.mutations.preKeys[k] = keyPair;
+    storePreKey(keyId, keyPair) {
+      return bufferedWrite('preKeys', keyId, keyPair,
+        () => state.storePreKey(keyId, keyPair));
     },
 
-    async removePreKey(keyId) {
-      const ctx = txStorage.getStore();
-      const k   = String(keyId);
-      if (!ctx) return state.removePreKey(keyId);
-      ctx.preKeys[k] = null;
-      ctx.mutations.preKeys[k] = null;
+    removePreKey(keyId) {
+      return bufferedWrite('preKeys', keyId, null, () => state.removePreKey(keyId));
     },
 
     // ── Signed pre-keys ───────────────────────────────────────────────────────
 
-    async loadSignedPreKey(keyId) {
-      const ctx = txStorage.getStore();
-      const k   = String(keyId);
-      if (!ctx) return state.loadSignedPreKey(keyId);
-      if (k in ctx.signedPreKeys) return ctx.signedPreKeys[k];
-      const val = await getMutex('signedPreKey').runExclusive(() => state.loadSignedPreKey(keyId));
-      ctx.signedPreKeys[k] = val;
-      ctx.dbQueries++;
-      return val;
+    loadSignedPreKey(keyId) {
+      return bufferedRead('signedPreKeys', 'signedPreKey', keyId,
+        () => state.loadSignedPreKey(keyId));
     },
 
-    async storeSignedPreKey(keyId, keyPair) {
-      const ctx = txStorage.getStore();
-      const k   = String(keyId);
-      if (!ctx) return state.storeSignedPreKey(keyId, keyPair);
-      ctx.signedPreKeys[k] = keyPair;
-      ctx.mutations.signedPreKeys[k] = keyPair;
+    storeSignedPreKey(keyId, keyPair) {
+      return bufferedWrite('signedPreKeys', keyId, keyPair,
+        () => state.storeSignedPreKey(keyId, keyPair));
     },
 
-    async removeSignedPreKey(keyId) {
-      const ctx = txStorage.getStore();
-      const k   = String(keyId);
-      if (!ctx) return state.removeSignedPreKey(keyId);
-      ctx.signedPreKeys[k] = null;
-      ctx.mutations.signedPreKeys[k] = null;
+    removeSignedPreKey(keyId) {
+      return bufferedWrite('signedPreKeys', keyId, null,
+        () => state.removeSignedPreKey(keyId));
     },
 
     // ── Identity keys ─────────────────────────────────────────────────────────
 
-    async loadIdentityKey(identifier) {
-      const ctx = txStorage.getStore();
-      if (!ctx) return state.loadIdentityKey(identifier);
-      if (identifier in ctx.identities) return ctx.identities[identifier];
-      const val = await getMutex('identity').runExclusive(() => state.loadIdentityKey(identifier));
-      ctx.identities[identifier] = val;
-      ctx.dbQueries++;
-      return val;
+    loadIdentityKey(identifier) {
+      return bufferedRead('identities', 'identity', identifier,
+        () => state.loadIdentityKey(identifier));
     },
 
     async saveIdentity(identifier, identityKey) {
@@ -534,32 +525,39 @@ function addTransactionCapability(state, logger, opts) {
       if (!ctx) return state.saveIdentity(identifier, identityKey);
       ctx.identities[identifier] = identityKey;
       ctx.mutations.identities[identifier] = identityKey;
-      // Inside a transaction we can't know yet if the key changed — return false
-      // (the actual changed-flag will be resolved at commit time by the store).
+      // The store answers whether the key changed, and that answer only exists
+      // once the write lands. Inside a transaction it has not, so say so.
       return false;
     },
 
     // ── Transaction control ───────────────────────────────────────────────────
 
-    /** Returns true if the current async context is inside a transaction. */
+    /** True when the current async context is inside a transaction. */
     isInTransaction,
 
+    /** Forwarded so a cache wrapped underneath can still be flushed. */
+    async flushCache() {
+      if (typeof state.flushCache === 'function') return state.flushCache();
+    },
+
     /**
      * Run `work` inside a transaction scoped to `key`.
+     *
      * @param {function} work  async function to execute
-     * @param {string}   key   mutex key (typically a key type or custom string)
+     * @param {string}   key   scope; separate keys run concurrently
      */
     transaction: async (work, key) => {
       key = key || 'default';
       const existing = txStorage.getStore();
 
-      // Nested transaction — reuse the enclosing context
+      // Nested transaction — reuse the enclosing context rather than opening a
+      // second one that would commit separately.
       if (existing) {
         logger && logger.trace('reusing existing transaction context');
         return work();
       }
 
-      const mutex = getMutex(key);
+      const mutex = getTxMutex(key);
       acquireRef(key);
 
       try {
@@ -581,6 +579,8 @@ function addTransactionCapability(state, logger, opts) {
       }
     }
   };
+
+  return _fillPassthrough(wrapper, state);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -588,18 +588,33 @@ function addTransactionCapability(state, logger, opts) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Returns the authenticated user's JID (phone@s.whatsapp.net) or throws
- * a descriptive error if the store is not yet fully authenticated.
+ * Returns the authenticated account's JID, or throws a descriptive error when
+ * the store is not authenticated yet.
+ *
+ * Use this anywhere the alternative is reaching for `store.phoneNumber` and
+ * hoping, so the failure arrives as a sentence rather than as a null reference
+ * several frames later.
+ *
+ * The JID the server assigned is preferred once there is one — on a companion
+ * it carries the device suffix, and rebuilding it from the phone number drops
+ * that silently. It is only trusted after registration, though: requesting a
+ * pairing code writes a placeholder `me` with no suffix before the exchange has
+ * happened, and returning that would defeat the point of the check.
  *
- * Use this anywhere we'd otherwise reach for `store.phoneNumber` directly,
- * to fail fast with a clear error instead of a silent null-reference crash.
+ * Works the same for both kinds of store. Only the wording of the error
+ * differs, because the way out of "not registered yet" is not the same.
  *
- * @param {object} store  — whalibmob store object (from createNewStore / loadStore)
- * @returns {string}       — JID string e.g. "40712345678@s.whatsapp.net"
- * @throws {Error}         — if store is not initialised or not yet registered
+ * @param {object} store  — store object (from createNewStore / createNewWebStore / loadStore)
+ * @returns {string}       — JID, e.g. "40712345678:12@s.whatsapp.net"
+ * @throws {Error}         — when the store is not initialised or not registered
  */
 function assertMeId(store) {
-  if (!store || !store.phoneNumber) {
+  if (!store) {
+    throw new Error(
+      'Cannot proceed: no store was given — call createNewStore() first'
+    );
+  }
+  if (!store.phoneNumber) {
     throw new Error(
       'Cannot proceed: store has no phoneNumber — call createNewStore() first'
     );
@@ -607,9 +622,15 @@ function assertMeId(store) {
   if (!store.registered) {
     throw new Error(
       'Cannot proceed: device is not registered yet — ' +
-      'complete SMS verification with verifyCode() before sending messages'
+      (store.mode === 'web'
+        ? 'link this device first, with a pairing code or by scanning the QR'
+        : 'complete SMS verification with verifyCode() before sending messages')
     );
   }
+
+  const assigned = store.me && store.me.id;
+  if (assigned) return String(assigned);
+
   const phone = String(store.phoneNumber).replace(/^\+/, '').replace(/\D/g, '');
   return `${phone}@s.whatsapp.net`;
 }
@@ -619,27 +640,32 @@ function assertMeId(store) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Creates a fresh set of whalibmob auth credentials (key pairs, registration ID,
- * device identifiers) for a given phone number.
+ * Creates a fresh set of auth credentials (key pairs, registration ID, device
+ * identifiers) for a given phone number.
  *
- * Returns whalibmob's store format (Buffer key pairs, signedPreKey as
- * { id, public, private, signature }).
+ * Returns the library's store format: Buffer key pairs, and signedPreKey as
+ * { id, public, private, signature }.
  *
  * A few extra fields (nextPreKeyId, firstUnuploadedPreKeyId, accountSyncCounter,
- * accountSettings, advSecretKey, etc.) are appended for account sync and for
+ * accountSettings, advSecretKey and so on) are appended for account sync and for
  * application code that expects them.
  *
- * @param {string|number} phoneNumber — full international number (e.g. "40712345678")
+ * This builds a store for the SMS flow. A companion device is registered by
+ * pairing rather than by SMS and needs the extra fields that go with it, so it
+ * has its own constructor — createNewWebStore — which starts from the same base
+ * as this one.
+ *
+ * @param {string|number} phoneNumber — full international number, e.g. "40712345678"
  * @param {object}        options     — optional overrides:
- *    registered {boolean}   — mark credentials as already registered (default false)
- *    name       {string}    — WhatsApp display name (default 'User')
- * @returns {object} fresh whalibmob store / credential object
+ *    registered {boolean}   — mark the credentials as already registered (default false)
+ *    name       {string}    — display name (default 'User')
+ * @returns {object} fresh store / credential object
  */
 function initAuthCreds(phoneNumber, options) {
   if (!phoneNumber) throw new Error('initAuthCreds: phoneNumber is required');
   options = options || {};
 
-  // Use whalibmob's own key-generation machinery (curve25519-js, proper prefixes)
+  // The library's own key generation — curve25519, with the right prefixes.
   const store = createNewStore(phoneNumber);
 
   // ── Extra credential fields ──────────────────────────────────────────────────
@@ -648,7 +674,7 @@ function initAuthCreds(phoneNumber, options) {
   /** Next pre-key ID to generate (monotonically increasing). */
   store.nextPreKeyId             = 1;
 
-  /** First pre-key ID not yet uploaded to the WhatsApp server. */
+  /** First pre-key ID not yet uploaded to the server. */
   store.firstUnuploadedPreKeyId  = 1;
 
   /** Sync counter used in account-sync IQ stanzas. */
@@ -657,16 +683,16 @@ function initAuthCreds(phoneNumber, options) {
   /** Account-level settings. */
   store.accountSettings          = { unarchiveChats: false };
 
-  /** Processed history messages — used to avoid duplicate handling on reconnect. */
+  /** Processed history messages — avoids handling the same one twice on reconnect. */
   store.processedHistoryMessages = [];
 
   /**
-   * 32-byte random secret used for ADV (multi-device) poll encryption.
+   * 32-byte random secret used for multi-device poll encryption.
    * Stored as a base64 string.
    */
   store.advSecretKey             = crypto.randomBytes(32).toString('base64');
 
-  // Fields that are undefined until populated by the pairing / registration flow
+  // Fields left undefined until the pairing / registration flow fills them in
   store.pairingCode              = undefined;
   store.lastPropHash             = undefined;
   store.routingInfo              = undefined;
@@ -687,5 +713,6 @@ module.exports = {
   makeCacheableSignalKeyStore,
   addTransactionCapability,
   assertMeId,
-  initAuthCreds
+  initAuthCreds,
+  SIGNAL_STORE_TTL_SECONDS
 };

package/package.json

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