zapo-js 1.9.0 → 1.10.0

package/README.md

@@ -127,19 +127,20 @@ The core lives at the repo root (`zapo-js`). Optional packages live in
 [`packages/`](packages/) and ship under the `@zapo-js/*` scope. Install
 only what you need.
 
-| Package                                              | Peer dependency                  | Purpose                                                                                                                                          |
-| ---------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [`@zapo-js/store-sqlite`](packages/store-sqlite)     | `better-sqlite3`                 | SQLite persistent store (single-process bots, dev sessions, small-to-medium prod).                                                               |
-| [`@zapo-js/store-redis`](packages/store-redis)       | `ioredis`                        | Redis-backed store with native TTL eviction.                                                                                                     |
-| [`@zapo-js/store-mongo`](packages/store-mongo)       | `mongodb`                        | MongoDB-backed store with TTL-index eviction.                                                                                                    |
-| [`@zapo-js/store-mysql`](packages/store-mysql)       | `mysql2`                         | MySQL / MariaDB-backed store with background cleanup poller.                                                                                     |
-| [`@zapo-js/store-postgres`](packages/store-postgres) | `pg`                             | PostgreSQL-backed store with background cleanup poller.                                                                                          |
-| [`@zapo-js/media-utils`](packages/media-utils)       | `sharp` + `file-type` + `ffmpeg` | `WaMediaProcessor`: thumbnails, waveforms, voice-note normalization.                                                                             |
-| [`@zapo-js/native`](packages/native)                 | (none)                           | Rust crypto accelerator for the messaging hot path (X25519 ECDH, XEdDSA sign / verify). Auto-detected once installed; ships as a WASM build.     |
-| [`@zapo-js/voip`](packages/voip)                     | `@roamhq/wrtc` + `libmlow-wasm`  | `client.voip` plugin for calls: MLow/WASM codec, SRTP, STUN, WebRTC/SCTP relay transport.                                                        |
-| [`@zapo-js/wam`](packages/wam)                       | (none)                           | `client.wam` plugin emitting the client-side WAM telemetry batches WA Web sends, for wire parity and anti-fingerprinting.                        |
-| [`@zapo-js/fake-server`](packages/fake-server)       | (none)                           | In-process fake WhatsApp Web server for end-to-end testing.                                                                                      |
-| [`@zapo-js/mcp-server`](packages/mcp-server)         | `@modelcontextprotocol/sdk`      | **Dev-only.** MCP server exposing multi-session `WaClient`s as dynamic tools for an LLM agent (Claude Code / Cursor / etc.). Not for production. |
+| Package                                              | Peer dependency                                                                       | Purpose                                                                                                                                          |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`@zapo-js/store-sqlite`](packages/store-sqlite)     | `better-sqlite3`                                                                      | SQLite persistent store (single-process bots, dev sessions, small-to-medium prod).                                                               |
+| [`@zapo-js/store-redis`](packages/store-redis)       | `ioredis`                                                                             | Redis-backed store with native TTL eviction.                                                                                                     |
+| [`@zapo-js/store-mongo`](packages/store-mongo)       | `mongodb`                                                                             | MongoDB-backed store with TTL-index eviction.                                                                                                    |
+| [`@zapo-js/store-mysql`](packages/store-mysql)       | `mysql2`                                                                              | MySQL / MariaDB-backed store with background cleanup poller.                                                                                     |
+| [`@zapo-js/store-postgres`](packages/store-postgres) | `pg`                                                                                  | PostgreSQL-backed store with background cleanup poller.                                                                                          |
+| [`@zapo-js/media-utils`](packages/media-utils)       | `sharp` + `file-type` + `ffmpeg`                                                      | `WaMediaProcessor`: thumbnails, waveforms, voice-note normalization.                                                                             |
+| [`@zapo-js/native`](packages/native)                 | (none)                                                                                | Rust crypto accelerator for the messaging hot path (X25519 ECDH, XEdDSA sign / verify). Auto-detected once installed; ships as a WASM build.     |
+| [`@zapo-js/voip`](packages/voip)                     | `@roamhq/wrtc` + `libmlow-wasm-fork`                                                  | `client.voip` plugin for calls: MLow/WASM codec, SRTP, STUN, WebRTC/SCTP relay transport.                                                        |
+| [`@zapo-js/voip-media`](packages/voip-media)         | `libmlow-wasm-fork` (optional, to carry media) + `@roamhq/wrtc` (optional, Node host) | Call media plane with no Node or `zapo-js` dependency, so it runs in the browser: relay transport, STUN, SRTP, RTP/RTCP, MLow codec.             |
+| [`@zapo-js/wam`](packages/wam)                       | (none)                                                                                | `client.wam` plugin emitting the client-side WAM telemetry batches WA Web sends, for wire parity and anti-fingerprinting.                        |
+| [`@zapo-js/fake-server`](packages/fake-server)       | (none)                                                                                | In-process fake WhatsApp Web server for end-to-end testing.                                                                                      |
+| [`@zapo-js/mcp-server`](packages/mcp-server)         | `@modelcontextprotocol/sdk`                                                           | **Dev-only.** MCP server exposing multi-session `WaClient`s as dynamic tools for an LLM agent (Claude Code / Cursor / etc.). Not for production. |
 
 Each package's README has the install + config + integration notes.
 

package/dist/client/WaClient.d.ts

@@ -132,6 +132,10 @@ declare class WaClientImpl extends EventEmitter {
      * arrays are empty. The predicate receives a parsed
      * {@link WaIgnoreKeyContext} and returns `true` to drop the stanza.
      *
+     * `category='peer'` messages from our own account (app-state key share,
+     * history sync, PDO responses) are never dropped: they are protocol
+     * traffic between our own devices, not chat messages.
+     *
      * @example
      * ```ts
      * client.ignoreKey({ remoteJid: spammerJid })

package/dist/client/WaClient.js

@@ -458,6 +458,10 @@ class WaClientImpl extends node_events_1.EventEmitter {
      * arrays are empty. The predicate receives a parsed
      * {@link WaIgnoreKeyContext} and returns `true` to drop the stanza.
      *
+     * `category='peer'` messages from our own account (app-state key share,
+     * history sync, PDO responses) are never dropped: they are protocol
+     * traffic between our own devices, not chat messages.
+     *
      * @example
      * ```ts
      * client.ignoreKey({ remoteJid: spammerJid })
@@ -469,7 +473,7 @@ class WaClientImpl extends node_events_1.EventEmitter {
         if (typeof input !== 'function') {
             (0, ignore_key_1.validateIgnoreKey)(input);
         }
-        const filter = (0, ignore_key_1.createIgnoreKeyFilter)(input, () => this.deps.authClient.getCurrentCredentials()?.meJid);
+        const filter = (0, ignore_key_1.createIgnoreKeyFilter)(input, () => this.deps.authClient.getCurrentCredentials());
         return this.deps.incomingNode.registerIncomingStanzaFilter(filter);
     }
     /** Auth client: pairing, credentials, registration state. */

package/dist/client/coordinators/WaMessageCoordinator.d.ts

@@ -384,10 +384,17 @@ export declare class WaMessageCoordinator {
      * the sealed request and resolves once the server answers with a
      * `mediaretry` notification, usually within a couple of seconds.
      *
-     * On `result: 'success'` only the `directPath` changes - the media key,
-     * hashes, and length of the original message stay valid, so patch the path
-     * into the message and download again. A second call for a message already
-     * in flight joins the first request instead of sending another receipt.
+     * On `result: 'success'` the media key, hashes, and length of the original
+     * message normally stay valid, so patch the fresh `directPath` into the
+     * message and download again. A second call for a message already in
+     * flight joins the first request instead of sending another receipt.
+     *
+     * A `success` is not a guarantee that the original key still opens the
+     * blob. Some primaries re-encrypt the file on every re-upload, and the
+     * re-served bytes then fail `fileEncSha256` and make `downloadBytes()`
+     * throw a MAC mismatch. Nothing in the round-trip carries key material for
+     * the new ciphertext, so the message cannot be recovered through this API
+     * and requesting another reupload will not help.
      *
      * The other three `result` values are answers too, not thrown errors:
      * `not_found` means the sender no longer holds the file and nothing can

package/dist/client/coordinators/WaMessageDispatchCoordinator.d.ts

@@ -7,6 +7,7 @@ import type { WaGroupEvent, WaOutgoingMessageEvent, WaSendMessageOptions, WaSign
 import type { Logger } from '../../infra/log/types';
 import { type WaSendContextInfo } from '../../message/context-info';
 import { type IcdcMeta } from '../../message/crypto/icdc';
+import { type WaOutboundMessageAttrs } from '../../message/encode/content';
 import type { WaEncryptedMessageInput, WaMessageBuildResult, WaMessagePublishOptions, WaMessagePublishResult, WaSendMessageContent, WaSendReceiptInput } from '../../message/types';
 import type { WaMessageClient } from '../../message/WaMessageClient';
 import { type Proto } from '../../proto';
@@ -96,6 +97,16 @@ export interface WaGroupHistoryAudience {
  * while nobody received anything.
  */
 export declare function restrictGroupHistoryTargets(message: Proto.IMessage, participantUserJids: readonly string[], senderJid: string, onDropped?: (droppedJids: readonly string[], totalExpected: number) => void): readonly string[];
+/**
+ * Resolves the stanza `type` and `enc.mediatype` of an outbound message. A
+ * `<biz>` companion rides a type=text stanza with no mediatype, except on a
+ * group list: there the server nacks with 479 (SMAX_INVALID) unless
+ * type=media, mediatype=list and `<biz><list>` travel together.
+ */
+export declare function resolveOutboundStanzaShape(attrs: Pick<WaOutboundMessageAttrs, 'buttonAddonKind' | 'typeAttr' | 'mediatype'>, isGroup: boolean): {
+    readonly type: string;
+    readonly mediatype: string | undefined;
+};
 export declare class WaMessageDispatchCoordinator {
     private readonly deps;
     private readonly mobileMessageIdFormat;

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaMessageDispatchCoordinator = void 0;
 exports.restrictGroupHistoryTargets = restrictGroupHistoryTargets;
+exports.resolveOutboundStanzaShape = resolveOutboundStanzaShape;
 const _crypto_1 = require("../../crypto");
 const primitives_1 = require("../../crypto/core/primitives");
 const PromiseDedup_1 = require("../../infra/perf/PromiseDedup");
@@ -73,6 +74,19 @@ function restrictGroupHistoryTargets(message, participantUserJids, senderJid, on
     }
     return targets;
 }
+/**
+ * Resolves the stanza `type` and `enc.mediatype` of an outbound message. A
+ * `<biz>` companion rides a type=text stanza with no mediatype, except on a
+ * group list: there the server nacks with 479 (SMAX_INVALID) unless
+ * type=media, mediatype=list and `<biz><list>` travel together.
+ */
+function resolveOutboundStanzaShape(attrs, isGroup) {
+    const flattensForAddon = attrs.buttonAddonKind !== null && !(isGroup && attrs.buttonAddonKind === 'list');
+    if (flattensForAddon) {
+        return { type: 'text', mediatype: undefined };
+    }
+    return { type: attrs.typeAttr, mediatype: attrs.mediatype ?? undefined };
+}
 class WaMessageDispatchCoordinator {
     constructor(options) {
         this.icdcDedup = new PromiseDedup_1.PromiseDedup();
@@ -403,12 +417,8 @@ class WaMessageDispatchCoordinator {
         const outboundAttrs = (0, content_1.resolveOutboundMessageAttrs)(messageWithIcdc);
         const buttonAddonKind = outboundAttrs.buttonAddonKind;
         const buttonAddonNode = buttonAddonKind ? (0, message_1.buildButtonAddonNode)(buttonAddonKind) : undefined;
-        // when a <biz> companion is attached the stanza must advertise type=text and
-        // omit enc.mediatype; sending type=media + mediatype=list/button alongside the
-        // companion is rejected by the server as SMAX_INVALID (479).
-        const type = buttonAddonKind ? 'text' : outboundAttrs.typeAttr;
+        const { type, mediatype } = resolveOutboundStanzaShape(outboundAttrs, isGroup);
         const edit = outboundAttrs.edit ?? undefined;
-        const mediatype = buttonAddonKind ? undefined : (outboundAttrs.mediatype ?? undefined);
         const metaAttrs = outboundAttrs.metaAttrs;
         const metaNode = metaAttrs ? (0, message_1.buildMetaNode)(metaAttrs) : undefined;
         const customNodes = [];

package/dist/client/messaging/ignore-key.d.ts

@@ -1,3 +1,4 @@
+import type { WaAuthCredentials } from '../../auth/types';
 import type { WaIgnoreKey, WaIgnoreKeyContext, WaIgnoreKeyPredicate, WaIncomingStanzaFilter } from '../types';
 import type { BinaryNode } from '../../transport/types';
 export declare function validateIgnoreKey(d: WaIgnoreKey): void;
@@ -8,4 +9,4 @@ export declare function validateIgnoreKey(d: WaIgnoreKey): void;
 export declare function extractIgnoreKeyContext(node: BinaryNode, meJid: string | null | undefined): WaIgnoreKeyContext | null;
 /** Pure matcher. Exported for direct testing without a coordinator. */
 export declare function matchesIgnoreKey(node: BinaryNode, d: WaIgnoreKey, meJid: string | null | undefined): boolean;
-export declare function createIgnoreKeyFilter(input: WaIgnoreKey | WaIgnoreKeyPredicate, getMeJid: () => string | null | undefined): WaIncomingStanzaFilter;
+export declare function createIgnoreKeyFilter(input: WaIgnoreKey | WaIgnoreKeyPredicate, getMe: () => Pick<WaAuthCredentials, 'meJid' | 'meLid'> | null | undefined): WaIncomingStanzaFilter;

package/dist/client/messaging/ignore-key.js

@@ -123,12 +123,33 @@ function matchesIgnoreKey(node, d, meJid) {
         return false;
     return true;
 }
-function createIgnoreKeyFilter(input, getMeJid) {
+/**
+ * A `category='peer'` message from our own account is traffic between our own
+ * devices (app-state key share, history sync, PDO responses), not a chat
+ * message, so it has no key to ignore by. Dropping it starves the protocol:
+ * app-state collections stay blocked on a key whose share never gets through.
+ * The own-account check keeps a foreign sender from dodging a filter by
+ * stamping the attribute.
+ */
+function isOwnPeerMessage(node, me) {
+    if (node.tag !== message_1.WA_MESSAGE_TAGS.MESSAGE || node.attrs.category !== 'peer' || !me) {
+        return false;
+    }
+    const from = node.attrs.from;
+    return !!from && tryParseJid(from) !== null && (0, jid_1.isOwnAccountJid)(from, me.meJid, me.meLid);
+}
+function createIgnoreKeyFilter(input, getMe) {
     if (typeof input === 'function') {
         return (node) => {
-            const ctx = extractIgnoreKeyContext(node, getMeJid());
+            const me = getMe();
+            if (isOwnPeerMessage(node, me))
+                return false;
+            const ctx = extractIgnoreKeyContext(node, me?.meJid);
             return ctx !== null && input(ctx);
         };
     }
-    return (node) => matchesIgnoreKey(node, input, getMeJid());
+    return (node) => {
+        const me = getMe();
+        return !isOwnPeerMessage(node, me) && matchesIgnoreKey(node, input, me?.meJid);
+    };
 }

package/dist/esm/client/WaClient.js

@@ -455,6 +455,10 @@ class WaClientImpl extends EventEmitter {
      * arrays are empty. The predicate receives a parsed
      * {@link WaIgnoreKeyContext} and returns `true` to drop the stanza.
      *
+     * `category='peer'` messages from our own account (app-state key share,
+     * history sync, PDO responses) are never dropped: they are protocol
+     * traffic between our own devices, not chat messages.
+     *
      * @example
      * ```ts
      * client.ignoreKey({ remoteJid: spammerJid })
@@ -466,7 +470,7 @@ class WaClientImpl extends EventEmitter {
         if (typeof input !== 'function') {
             validateIgnoreKey(input);
         }
-        const filter = createIgnoreKeyFilter(input, () => this.deps.authClient.getCurrentCredentials()?.meJid);
+        const filter = createIgnoreKeyFilter(input, () => this.deps.authClient.getCurrentCredentials());
         return this.deps.incomingNode.registerIncomingStanzaFilter(filter);
     }
     /** Auth client: pairing, credentials, registration state. */

package/dist/esm/client/coordinators/WaMessageDispatchCoordinator.js

@@ -69,6 +69,19 @@ export function restrictGroupHistoryTargets(message, participantUserJids, sender
     }
     return targets;
 }
+/**
+ * Resolves the stanza `type` and `enc.mediatype` of an outbound message. A
+ * `<biz>` companion rides a type=text stanza with no mediatype, except on a
+ * group list: there the server nacks with 479 (SMAX_INVALID) unless
+ * type=media, mediatype=list and `<biz><list>` travel together.
+ */
+export function resolveOutboundStanzaShape(attrs, isGroup) {
+    const flattensForAddon = attrs.buttonAddonKind !== null && !(isGroup && attrs.buttonAddonKind === 'list');
+    if (flattensForAddon) {
+        return { type: 'text', mediatype: undefined };
+    }
+    return { type: attrs.typeAttr, mediatype: attrs.mediatype ?? undefined };
+}
 export class WaMessageDispatchCoordinator {
     constructor(options) {
         this.icdcDedup = new PromiseDedup();
@@ -399,12 +412,8 @@ export class WaMessageDispatchCoordinator {
         const outboundAttrs = resolveOutboundMessageAttrs(messageWithIcdc);
         const buttonAddonKind = outboundAttrs.buttonAddonKind;
         const buttonAddonNode = buttonAddonKind ? buildButtonAddonNode(buttonAddonKind) : undefined;
-        // when a <biz> companion is attached the stanza must advertise type=text and
-        // omit enc.mediatype; sending type=media + mediatype=list/button alongside the
-        // companion is rejected by the server as SMAX_INVALID (479).
-        const type = buttonAddonKind ? 'text' : outboundAttrs.typeAttr;
+        const { type, mediatype } = resolveOutboundStanzaShape(outboundAttrs, isGroup);
         const edit = outboundAttrs.edit ?? undefined;
-        const mediatype = buttonAddonKind ? undefined : (outboundAttrs.mediatype ?? undefined);
         const metaAttrs = outboundAttrs.metaAttrs;
         const metaNode = metaAttrs ? buildMetaNode(metaAttrs) : undefined;
         const customNodes = [];

package/dist/esm/client/messaging/ignore-key.js

@@ -1,4 +1,4 @@
-import { parseJidFull } from '../../protocol/jid.js';
+import { isOwnAccountJid, parseJidFull } from '../../protocol/jid.js';
 import { WA_MESSAGE_TAGS } from '../../protocol/message.js';
 import { WA_NODE_TAGS } from '../../protocol/nodes.js';
 const TAG_TO_KIND = {
@@ -117,12 +117,33 @@ export function matchesIgnoreKey(node, d, meJid) {
         return false;
     return true;
 }
-export function createIgnoreKeyFilter(input, getMeJid) {
+/**
+ * A `category='peer'` message from our own account is traffic between our own
+ * devices (app-state key share, history sync, PDO responses), not a chat
+ * message, so it has no key to ignore by. Dropping it starves the protocol:
+ * app-state collections stay blocked on a key whose share never gets through.
+ * The own-account check keeps a foreign sender from dodging a filter by
+ * stamping the attribute.
+ */
+function isOwnPeerMessage(node, me) {
+    if (node.tag !== WA_MESSAGE_TAGS.MESSAGE || node.attrs.category !== 'peer' || !me) {
+        return false;
+    }
+    const from = node.attrs.from;
+    return !!from && tryParseJid(from) !== null && isOwnAccountJid(from, me.meJid, me.meLid);
+}
+export function createIgnoreKeyFilter(input, getMe) {
     if (typeof input === 'function') {
         return (node) => {
-            const ctx = extractIgnoreKeyContext(node, getMeJid());
+            const me = getMe();
+            if (isOwnPeerMessage(node, me))
+                return false;
+            const ctx = extractIgnoreKeyContext(node, me?.meJid);
             return ctx !== null && input(ctx);
         };
     }
-    return (node) => matchesIgnoreKey(node, input, getMeJid());
+    return (node) => {
+        const me = getMe();
+        return !isOwnPeerMessage(node, me) && matchesIgnoreKey(node, input, me?.meJid);
+    };
 }

package/dist/esm/store/cache/identity.cache.js

@@ -1,18 +1,41 @@
 import { WaIdentityMemoryStore } from '../memory/identity.store.js';
+import { IdleExpiryIndex } from '../../util/collections.js';
+/** L1 with idle expiry; hits keep it in access order, so the cap evicts the LRU entry. */
+class IdleIdentityMemoryStore extends WaIdentityMemoryStore {
+    constructor(maxRemoteIdentities, expiry) {
+        super({ maxRemoteIdentities });
+        this.idle = new IdleExpiryIndex(this.remoteIdentities, expiry);
+    }
+    detach() {
+        this.idle.detach();
+    }
+    onEntryAccess(key) {
+        this.idle.touch(key);
+    }
+    onEntryRemove(key) {
+        this.idle.delete(key);
+    }
+    onEntriesClear() {
+        this.idle.clear();
+    }
+}
 /**
  * Read-through / write-through in-process cache for a persistent remote
- * identity backend. Reuses {@link WaIdentityMemoryStore} as the bounded-LRU
- * L1. Remote identities are read alongside sessions on the send path (the
+ * identity backend. Reuses {@link WaIdentityMemoryStore} as the bounded L1.
+ * Remote identities are read alongside sessions on the send path (the
  * identity-mismatch guard), so caching them complements
- * {@link withSessionCache}.
+ * {@link withSessionCache}, which also describes the eviction with and
+ * without `expiry`.
  *
  * The identity store has no per-key delete: identities are overwritten on
  * re-establishment, so a peer's key change propagates through the
  * write-through `setRemoteIdentity`. See {@link withSessionCache} for the
  * shared coherence model and the single-writer-per-session assumption.
  */
-export function withIdentityCache(backend, maxEntries) {
-    const l1 = new WaIdentityMemoryStore({ maxRemoteIdentities: maxEntries });
+export function withIdentityCache(backend, maxEntries, expiry) {
+    const l1 = expiry
+        ? new IdleIdentityMemoryStore(maxEntries, expiry)
+        : new WaIdentityMemoryStore({ maxRemoteIdentities: maxEntries });
     let generation = 0;
     return {
         getRemoteIdentity: async (address) => {
@@ -68,6 +91,8 @@ export function withIdentityCache(backend, maxEntries) {
             await l1.clear();
         },
         destroy: async () => {
+            if (l1 instanceof IdleIdentityMemoryStore)
+                l1.detach();
             await l1.clear();
             await backend.destroy?.();
         }

package/dist/esm/store/cache/privacy-token.cache.js

@@ -1,18 +1,41 @@
 import { WaPrivacyTokenMemoryStore } from '../memory/privacy-token.store.js';
+import { IdleExpiryIndex } from '../../util/collections.js';
+/** L1 with idle expiry; hits keep it in access order, so the cap evicts the LRU entry. */
+class IdlePrivacyTokenMemoryStore extends WaPrivacyTokenMemoryStore {
+    constructor(maxEntries, expiry) {
+        super(maxEntries);
+        this.idle = new IdleExpiryIndex(this.records, expiry);
+    }
+    detach() {
+        this.idle.detach();
+    }
+    onEntryAccess(jid) {
+        this.idle.touch(jid);
+    }
+    onEntryRemove(jid) {
+        this.idle.delete(jid);
+    }
+    onEntriesClear() {
+        this.idle.clear();
+    }
+}
 /**
  * Read-through cache for a persistent privacy-token backend. Reuses
- * {@link WaPrivacyTokenMemoryStore} as the bounded-LRU L1.
+ * {@link WaPrivacyTokenMemoryStore} as the bounded L1.
  *
  * Unlike the signal caches this is **invalidate-on-write, not
  * write-through**: `upsert` merges partial fields into the existing row on
  * the backend, so caching the partial incoming record would diverge from the
  * backend's merged result. Instead each upsert drops the L1 entry and the
  * next read re-populates from the merged backend truth. See
- * {@link withSessionCache} for the shared coherence model and the
- * single-writer-per-session assumption.
+ * {@link withSessionCache} for the shared coherence model, the
+ * single-writer-per-session assumption and the eviction with and without
+ * `expiry`.
  */
-export function withPrivacyTokenCache(backend, maxEntries) {
-    const l1 = new WaPrivacyTokenMemoryStore(maxEntries);
+export function withPrivacyTokenCache(backend, maxEntries, expiry) {
+    const l1 = expiry
+        ? new IdlePrivacyTokenMemoryStore(maxEntries, expiry)
+        : new WaPrivacyTokenMemoryStore(maxEntries);
     let generation = 0;
     return {
         upsert: async (record) => {
@@ -50,6 +73,8 @@ export function withPrivacyTokenCache(backend, maxEntries) {
             await l1.clear();
         },
         destroy: async () => {
+            if (l1 instanceof IdlePrivacyTokenMemoryStore)
+                l1.detach();
             await l1.clear();
             await backend.destroy?.();
         }

package/dist/esm/store/cache/sender-key.cache.js

@@ -1,7 +1,33 @@
 import { SenderKeyMemoryStore } from '../memory/sender-key.store.js';
+import { IdleExpiryIndex } from '../../util/collections.js';
+/** L1 with idle expiry; hits keep both maps in access order, so the caps evict LRU entries. */
+class IdleSenderKeyMemoryStore extends SenderKeyMemoryStore {
+    constructor(maxEntries, expiry) {
+        super({ maxSenderKeys: maxEntries, maxSenderDistributions: maxEntries });
+        this.idleSenderKeys = new IdleExpiryIndex(this.senderKeys, expiry);
+        this.idleDistributions = new IdleExpiryIndex(this.senderDistributions, expiry);
+    }
+    detach() {
+        this.idleSenderKeys.detach();
+        this.idleDistributions.detach();
+    }
+    onEntryAccess(entries, key) {
+        this.indexFor(entries).touch(key);
+    }
+    onEntryRemove(entries, key) {
+        this.indexFor(entries).delete(key);
+    }
+    onEntriesClear() {
+        this.idleSenderKeys.clear();
+        this.idleDistributions.clear();
+    }
+    indexFor(entries) {
+        return entries === this.senderKeys ? this.idleSenderKeys : this.idleDistributions;
+    }
+}
 /**
  * Read-through / write-through in-process cache for a persistent sender-key
- * backend. Reuses {@link SenderKeyMemoryStore} as the bounded-LRU L1 so the
+ * backend. Reuses {@link SenderKeyMemoryStore} as the bounded L1 so the
  * per-(group, sender) lookups repeated across a group fan-out skip the
  * backend round-trip.
  *
@@ -12,13 +38,16 @@ import { SenderKeyMemoryStore } from '../memory/sender-key.store.js';
  * (`deleteDeviceSenderKey`/`markForgetSenderKey`) run on the backend for the
  * authoritative count and then invalidate the matching L1 entries via the
  * memory store's own sweep. See {@link withSessionCache} for the shared
- * coherence model and the single-writer-per-session assumption.
+ * coherence model, the single-writer-per-session assumption and the eviction
+ * with and without `expiry`.
  */
-export function withSenderKeyCache(backend, maxEntries) {
-    const l1 = new SenderKeyMemoryStore({
-        maxSenderKeys: maxEntries,
-        maxSenderDistributions: maxEntries
-    });
+export function withSenderKeyCache(backend, maxEntries, expiry) {
+    const l1 = expiry
+        ? new IdleSenderKeyMemoryStore(maxEntries, expiry)
+        : new SenderKeyMemoryStore({
+            maxSenderKeys: maxEntries,
+            maxSenderDistributions: maxEntries
+        });
     let generation = 0;
     return {
         upsertSenderKey: async (record) => {
@@ -94,6 +123,8 @@ export function withSenderKeyCache(backend, maxEntries) {
             await l1.clear();
         },
         destroy: async () => {
+            if (l1 instanceof IdleSenderKeyMemoryStore)
+                l1.detach();
             await l1.clear();
             await backend.destroy?.();
         }

package/dist/esm/store/cache/session.cache.js

@@ -1,9 +1,31 @@
 import { WaSessionMemoryStore } from '../memory/session.store.js';
+import { IdleExpiryIndex } from '../../util/collections.js';
+/** L1 with idle expiry; hits keep it in access order, so the cap evicts the LRU entry. */
+class IdleSessionMemoryStore extends WaSessionMemoryStore {
+    constructor(maxSessions, expiry) {
+        super({ maxSessions });
+        this.idle = new IdleExpiryIndex(this.signalSessions, expiry);
+    }
+    detach() {
+        this.idle.detach();
+    }
+    onEntryAccess(key) {
+        this.idle.touch(key);
+    }
+    onEntryRemove(key) {
+        this.idle.delete(key);
+    }
+    onEntriesClear() {
+        this.idle.clear();
+    }
+}
 /**
  * Read-through / write-through in-process cache for a persistent session
- * backend. Reuses {@link WaSessionMemoryStore} as the bounded-LRU L1 so that
+ * backend. Reuses {@link WaSessionMemoryStore} as the bounded L1 so that
  * repeated reads of the same peer on the send/recv path skip the backend
- * round-trip.
+ * round-trip. Without `expiry` the cap evicts the least recently written
+ * entry; with it, the least recently used, and entries idle past the TTL
+ * leave the L1 (never the backend) and are re-read on next use.
  *
  * Coherence model (single process):
  * - every mutation (set/delete/clear) writes the backend then the L1 in
@@ -19,8 +41,10 @@ import { WaSessionMemoryStore } from '../memory/session.store.js';
  * session with the cache enabled - there is no cross-process invalidation
  * channel, so another process's writes would leave this L1 stale.
  */
-export function withSessionCache(backend, maxEntries) {
-    const l1 = new WaSessionMemoryStore({ maxSessions: maxEntries });
+export function withSessionCache(backend, maxEntries, expiry) {
+    const l1 = expiry
+        ? new IdleSessionMemoryStore(maxEntries, expiry)
+        : new WaSessionMemoryStore({ maxSessions: maxEntries });
     let generation = 0;
     return {
         hasSession: async (address) => {
@@ -85,6 +109,8 @@ export function withSessionCache(backend, maxEntries) {
             await l1.clear();
         },
         destroy: async () => {
+            if (l1 instanceof IdleSessionMemoryStore)
+                l1.detach();
             await l1.clear();
             await backend.destroy?.();
         }

package/dist/esm/store/createStore.js

@@ -35,6 +35,7 @@ import { WaSignalMemoryStore } from './memory/signal.store.js';
 import { WaThreadMemoryStore } from './memory/thread.store.js';
 import { NOOP_CHAT_METADATA_STORE, NOOP_CONTACT_STORE, NOOP_DEVICE_LIST_STORE, NOOP_GROUP_METADATA_STORE, NOOP_MESSAGE_SECRET_STORE, NOOP_MESSAGE_STORE, NOOP_RETRY_STORE, NOOP_THREAD_STORE } from './noop.store.js';
 import { resolvePositive } from '../util/coercion.js';
+import { IdleSweepClock, resolveIdleSweepPeriodMs } from '../util/collections.js';
 import { toError } from '../util/primitives.js';
 const DEFAULT_CACHE_TTLS_MS = Object.freeze({
     retryMs: 60 * 1000,
@@ -56,6 +57,8 @@ const REQUIRED_PROVIDER_DOMAINS = [
     'contacts',
     'privacyToken'
 ];
+const CACHE_LAYER_DOMAINS = ['session', 'identity', 'senderKey', 'privacyToken'];
+const MIN_CACHE_LAYER_TTL_MS = 1000;
 function hasDestroy(value) {
     return (!!value &&
         typeof value === 'object' &&
@@ -70,6 +73,37 @@ async function destroyIfSupported(value) {
 function usesBackend(provider) {
     return !!provider && provider !== 'memory' && provider !== 'none';
 }
+/**
+ * Validates `cacheLayer.ttlMs` and hands each domain that gets an L1 its idle
+ * expiry, all on one clock. A TTL on a domain without an L1 is warned and dropped.
+ */
+function resolveCacheLayerExpiry(cacheLayer, providers, logger) {
+    const ttls = [];
+    for (const domain of CACHE_LAYER_DOMAINS) {
+        const ttlMs = cacheLayer.ttlMs?.[`${domain}Ms`];
+        if (ttlMs === undefined)
+            continue;
+        if (!Number.isSafeInteger(ttlMs) || ttlMs < MIN_CACHE_LAYER_TTL_MS) {
+            throw new Error(`cacheLayer.ttlMs.${domain}Ms must be a safe integer >= ${MIN_CACHE_LAYER_TTL_MS}`);
+        }
+        if (cacheLayer[domain] && usesBackend(providers[domain])) {
+            ttls.push({ domain, ttlMs });
+            continue;
+        }
+        logger?.warn('cacheLayer ttl ignored: domain has no L1', {
+            domain,
+            cached: cacheLayer[domain] === true,
+            provider: providers[domain] ?? 'memory'
+        });
+    }
+    const expiry = {};
+    if (ttls.length === 0)
+        return expiry;
+    const clock = new IdleSweepClock(resolveIdleSweepPeriodMs(ttls.map((entry) => entry.ttlMs)));
+    for (const { domain, ttlMs } of ttls)
+        expiry[domain] = { clock, ttlMs };
+    return expiry;
+}
 function resolveStore(sessionId, backends, provider, domain, kind, fallback) {
     if (!provider || provider === 'memory' || provider === 'none') {
         return fallback();
@@ -112,6 +146,7 @@ export function createStore(options) {
         deviceList: resolvePositive(options.memory?.cacheTtlMs?.deviceListMs, DEFAULT_CACHE_TTLS_MS.deviceListMs, 'memory.cacheTtlMs.deviceListMs'),
         messageSecret: resolvePositive(options.memory?.cacheTtlMs?.messageSecretMs, DEFAULT_CACHE_TTLS_MS.messageSecretMs, 'memory.cacheTtlMs.messageSecretMs')
     });
+    const cacheLayerExpiry = resolveCacheLayerExpiry(cacheLayer, providers, storeLogger);
     const sessions = new Map();
     const pendingSessionDestroys = new Set();
     let storeDestroyed = false;
@@ -208,20 +243,20 @@ export function createStore(options) {
             const signalStore = withSignalLock(rawSignal);
             const preKeyStore = withPreKeyLock(rawPreKey);
             const sessionStore = withSessionLock(cacheLayer.session && usesBackend(providers.session)
-                ? withSessionCache(rawSession, cacheLayer.limits?.session)
+                ? withSessionCache(rawSession, cacheLayer.limits?.session, cacheLayerExpiry.session)
                 : rawSession);
             const identityStore = withIdentityLock(cacheLayer.identity && usesBackend(providers.identity)
-                ? withIdentityCache(rawIdentity, cacheLayer.limits?.identity)
+                ? withIdentityCache(rawIdentity, cacheLayer.limits?.identity, cacheLayerExpiry.identity)
                 : rawIdentity);
             const senderKeyStore = withSenderKeyLock(cacheLayer.senderKey && usesBackend(providers.senderKey)
-                ? withSenderKeyCache(rawSenderKey, cacheLayer.limits?.senderKey)
+                ? withSenderKeyCache(rawSenderKey, cacheLayer.limits?.senderKey, cacheLayerExpiry.senderKey)
                 : rawSenderKey);
             const appStateStore = withAppStateLock(rawAppState);
             const messageStore = withMessageLock(rawMessages);
             const threadStore = withThreadLock(rawThreads);
             const contactStore = withContactLock(rawContacts);
             const privacyTokenStore = withPrivacyTokenLock(cacheLayer.privacyToken && usesBackend(providers.privacyToken)
-                ? withPrivacyTokenCache(rawPrivacyToken, cacheLayer.limits?.privacyToken)
+                ? withPrivacyTokenCache(rawPrivacyToken, cacheLayer.limits?.privacyToken, cacheLayerExpiry.privacyToken)
                 : rawPrivacyToken);
             let sessionDestroyed = false;
             let destroyPromise = null;