zapo-js 0.3.0 → 1.0.0

package/dist/esm/signal/session/resolver.js

@@ -3,20 +3,27 @@ import { PromiseDedup } from '../../infra/perf/PromiseDedup.js';
 import { normalizeDeviceJid, parseSignalAddressFromJid, signalAddressKey } from '../../protocol/jid.js';
 import { bytesToHex, uint8Equal } from '../../util/bytes.js';
 import { toError } from '../../util/primitives.js';
+/** Builds a {@link SignalSessionResolver} backed by the given Signal APIs and stores. */
 export function createSignalSessionResolver(options) {
     const { signalProtocol, sessionStore, identityStore, signalIdentitySync, signalSessionSync, logger } = options;
     const dedup = new PromiseDedup();
-    const ensureSessionInternal = async (address, jid, expectedIdentity, reasonIdentity = false, prefetchedBundle) => {
+    const ensureSessionInternal = async (address, jid, expectedIdentity, reasonIdentity = false, prefetchedBundle, knownAbsent = false) => {
+        const jidLogger = logger.child({ jid });
         const expectedSerializedIdentity = expectedIdentity
             ? toSerializedPubKey(expectedIdentity)
             : null;
         if (reasonIdentity) {
             await signalIdentitySync.syncIdentityKeys([jid]);
         }
-        if (await sessionStore.hasSession(address)) {
+        if (!knownAbsent && (await sessionStore.hasSession(address))) {
             if (expectedSerializedIdentity) {
                 const storedIdentity = await identityStore.getRemoteIdentity(address);
                 if (!storedIdentity || !uint8Equal(storedIdentity, expectedSerializedIdentity)) {
+                    jidLogger.warn('signal identity mismatch on stored identity', {
+                        source: 'stored_vs_expected',
+                        expected: bytesToHex(expectedSerializedIdentity),
+                        stored: storedIdentity ? bytesToHex(storedIdentity) : null
+                    });
                     throw new Error('identity mismatch');
                 }
             }
@@ -30,7 +37,7 @@ export function createSignalSessionResolver(options) {
             };
         }
         else {
-            logger.info('signal session missing, fetching remote key bundle', { jid });
+            jidLogger.debug('signal session missing, fetching remote key bundle');
             fetched = await signalSessionSync.fetchKeyBundle({
                 jid,
                 reasonIdentity
@@ -40,26 +47,40 @@ export function createSignalSessionResolver(options) {
         if (reasonIdentity) {
             const storedIdentity = await identityStore.getRemoteIdentity(address);
             if (storedIdentity && !uint8Equal(remoteIdentity, storedIdentity)) {
+                jidLogger.warn('signal identity mismatch on fetched bundle vs stored', {
+                    source: 'remote_vs_stored',
+                    remote: bytesToHex(remoteIdentity),
+                    stored: bytesToHex(storedIdentity)
+                });
                 throw new Error('identity mismatch');
             }
         }
         if (expectedSerializedIdentity && !uint8Equal(remoteIdentity, expectedSerializedIdentity)) {
+            jidLogger.warn('signal identity mismatch on fetched bundle vs expected', {
+                source: 'remote_vs_expected',
+                remote: bytesToHex(remoteIdentity),
+                expected: bytesToHex(expectedSerializedIdentity)
+            });
             throw new Error('identity mismatch');
         }
         const session = await signalProtocol.establishOutgoingSession(address, fetched.bundle, {
-            reuseExisting: true
+            reuseExisting: true,
+            knownAbsent
         });
-        logger.info('signal session synchronized', {
-            jid,
+        jidLogger.debug('signal session synchronized', {
             regId: fetched.bundle.regId,
             hasOneTimeKey: fetched.bundle.oneTimeKey !== undefined
         });
         return session;
     };
-    const ensureSessionWithDedup = (address, jid, expectedIdentity, reasonIdentity = false, prefetchedBundle) => {
+    const ensureSessionWithDedup = (address, jid, expectedIdentity, reasonIdentity = false, prefetchedBundle, knownAbsent = false) => {
         const expectedIdentityKey = expectedIdentity ? bytesToHex(expectedIdentity) : 'none';
-        const dedupKey = `signalSession:${signalAddressKey(address)}:${reasonIdentity ? '1' : '0'}:${expectedIdentityKey}`;
-        return dedup.run(dedupKey, () => ensureSessionInternal(address, jid, expectedIdentity, reasonIdentity, prefetchedBundle));
+        // knownAbsent is part of the dedup key: single-caller (false) and
+        // batch (true) must NOT share a Promise, or the unsafe variant
+        // could leak to the safe caller. Per-address lock + the recheck
+        // inside persistOutgoingSessionsBatch resolves any race.
+        const dedupKey = `signalSession:${signalAddressKey(address)}:${reasonIdentity ? '1' : '0'}:${expectedIdentityKey}:${knownAbsent ? '1' : '0'}`;
+        return dedup.run(dedupKey, () => ensureSessionInternal(address, jid, expectedIdentity, reasonIdentity, prefetchedBundle, knownAbsent));
     };
     const ensureSession = (address, jid, expectedIdentity, reasonIdentity = false) => ensureSessionWithDedup(address, jid, expectedIdentity, reasonIdentity).then(() => { });
     const ensureSessionsBatch = async (targetJids, expectedIdentityByJid) => {
@@ -120,7 +141,14 @@ export function createSignalSessionResolver(options) {
             const session = resolvedByIndex[index];
             const expectedIdentity = normalizedExpectedIdentityByJid?.get(normalizedTargetJids[index]);
             if (session && expectedIdentity) {
-                if (!uint8Equal(session.remote.pubKey, toSerializedPubKey(expectedIdentity))) {
+                const expectedSerialized = toSerializedPubKey(expectedIdentity);
+                if (!uint8Equal(session.remote.pubKey, expectedSerialized)) {
+                    logger.warn('signal identity mismatch on existing session vs expected', {
+                        jid: normalizedTargetJids[index],
+                        source: 'session_vs_expected',
+                        session: bytesToHex(session.remote.pubKey),
+                        expected: bytesToHex(expectedSerialized)
+                    });
                     throw new Error('identity mismatch');
                 }
             }
@@ -146,51 +174,132 @@ export function createSignalSessionResolver(options) {
             });
             return collectResolvedTargets();
         }
-        const ensuredTargetIndices = new Array(missingIndices.length);
-        const ensurePromises = new Array(missingIndices.length);
-        let ensureCount = 0;
+        // Prepare under per-address locks (no persist). Bulk persist below
+        // holds every per-address lock at once via persistOutgoingSessionsBatch.
+        const prepareTargetIndices = new Array(missingIndices.length);
+        const preparePromises = new Array(missingIndices.length);
+        let prepareCount = 0;
+        const missingBundleTargets = [];
         for (let index = 0; index < missingIndices.length; index += 1) {
             const targetIndex = missingIndices[index];
             const targetJid = normalizedTargetJids[targetIndex];
             const batchResult = batchResults[index];
             if (!batchResult?.bundle) {
-                logger.warn('signal batch key fetch returned target without bundle', {
+                missingBundleTargets.push({
                     jid: targetJid,
-                    message: batchResult?.errorText ?? 'missing key bundle user in response'
+                    reason: batchResult?.errorText ?? 'missing key bundle user in response'
                 });
                 continue;
             }
             const expectedIdentity = normalizedExpectedIdentityByJid?.get(targetJid);
-            ensuredTargetIndices[ensureCount] = targetIndex;
-            ensurePromises[ensureCount] = ensureSessionWithDedup(normalizedTargetAddresses[targetIndex], targetJid, expectedIdentity, false, batchResult.bundle);
-            ensureCount += 1;
+            const expectedSerializedIdentity = expectedIdentity
+                ? toSerializedPubKey(expectedIdentity)
+                : null;
+            const bundleIdentity = toSerializedPubKey(batchResult.bundle.identity);
+            if (expectedSerializedIdentity &&
+                !uint8Equal(bundleIdentity, expectedSerializedIdentity)) {
+                logger.warn('signal identity mismatch on fetched batch bundle vs expected', {
+                    jid: targetJid,
+                    source: 'bundle_vs_expected',
+                    bundle: bytesToHex(bundleIdentity),
+                    expected: bytesToHex(expectedSerializedIdentity)
+                });
+                throw new Error('identity mismatch');
+            }
+            const targetAddress = normalizedTargetAddresses[targetIndex];
+            const bundle = batchResult.bundle;
+            prepareTargetIndices[prepareCount] = targetIndex;
+            preparePromises[prepareCount] = signalProtocol
+                .prepareOutgoingSession(targetAddress, bundle, {
+                reuseExisting: true,
+                knownAbsent: true
+            })
+                .then((prep) => ({
+                session: prep.session,
+                remoteIdentity: prep.remoteIdentity
+            }));
+            prepareCount += 1;
+        }
+        if (missingBundleTargets.length > 0) {
+            logger.warn('signal batch key fetch returned targets without bundle', {
+                droppedCount: missingBundleTargets.length,
+                totalRequested: missingIndices.length,
+                sample: missingBundleTargets.slice(0, 3)
+            });
         }
-        if (ensureCount === 0) {
+        if (prepareCount === 0) {
             return collectResolvedTargets();
         }
-        ensuredTargetIndices.length = ensureCount;
-        ensurePromises.length = ensureCount;
-        const ensureResults = await Promise.allSettled(ensurePromises);
+        prepareTargetIndices.length = prepareCount;
+        preparePromises.length = prepareCount;
+        const prepareResults = await Promise.allSettled(preparePromises);
+        const batchEntries = [];
+        const entryToTargetIndex = [];
         const fallbackIndices = [];
-        for (let index = 0; index < ensuredTargetIndices.length; index += 1) {
-            const targetIndex = ensuredTargetIndices[index];
-            const ensureResult = ensureResults[index];
-            if (ensureResult.status === 'rejected') {
-                const normalized = toError(ensureResult.reason);
+        for (let i = 0; i < prepareTargetIndices.length; i += 1) {
+            const targetIndex = prepareTargetIndices[i];
+            const result = prepareResults[i];
+            if (result.status === 'rejected') {
+                const normalized = toError(result.reason);
                 if (normalized.message === 'identity mismatch') {
                     throw normalized;
                 }
-                logger.warn('signal session ensure failed during batch resolution', {
+                logger.warn('signal session prepare failed during batch resolution', {
                     jid: normalizedTargetJids[targetIndex],
                     message: normalized.message
                 });
                 continue;
             }
-            const session = ensureResult.value;
+            batchEntries.push({
+                address: normalizedTargetAddresses[targetIndex],
+                session: result.value.session,
+                remoteIdentity: result.value.remoteIdentity
+            });
+            entryToTargetIndex.push(targetIndex);
+        }
+        if (batchEntries.length === 0) {
+            return collectResolvedTargets();
+        }
+        let persistResult;
+        try {
+            persistResult = await signalProtocol.persistOutgoingSessionsBatch(batchEntries);
+        }
+        catch (error) {
+            const normalized = toError(error);
+            logger.warn('signal batched session persist failed', {
+                requested: batchEntries.length,
+                message: normalized.message
+            });
+            for (let i = 0; i < entryToTargetIndex.length; i += 1) {
+                fallbackIndices.push(entryToTargetIndex[i]);
+            }
+            persistResult = { resolved: [], skipped: [] };
+        }
+        const sessionByAddressKey = new Map();
+        for (const r of persistResult.resolved) {
+            sessionByAddressKey.set(signalAddressKey(r.address), r.session);
+        }
+        const skippedByAddressKey = new Set();
+        for (const s of persistResult.skipped) {
+            skippedByAddressKey.add(signalAddressKey(s.address));
+            logger.warn('signal session persist skipped due to identity conflict', {
+                user: s.address.user,
+                server: s.address.server,
+                device: s.address.device
+            });
+        }
+        for (let i = 0; i < entryToTargetIndex.length; i += 1) {
+            const targetIndex = entryToTargetIndex[i];
+            const addrKey = signalAddressKey(normalizedTargetAddresses[targetIndex]);
+            const session = sessionByAddressKey.get(addrKey);
             if (session) {
                 resolvedByIndex[targetIndex] = session;
+                continue;
+            }
+            if (skippedByAddressKey.has(addrKey)) {
+                continue;
             }
-            else {
+            if (!fallbackIndices.includes(targetIndex)) {
                 fallbackIndices.push(targetIndex);
             }
         }

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

@@ -0,0 +1,75 @@
+import { WaIdentityMemoryStore } from '../memory/identity.store.js';
+/**
+ * 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-mismatch guard), so caching them complements
+ * {@link withSessionCache}.
+ *
+ * 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 });
+    let generation = 0;
+    return {
+        getRemoteIdentity: async (address) => {
+            const cached = await l1.getRemoteIdentity(address);
+            if (cached !== null)
+                return cached;
+            const gen = generation;
+            const fetched = await backend.getRemoteIdentity(address);
+            if (fetched !== null &&
+                gen === generation &&
+                (await l1.getRemoteIdentity(address)) === null) {
+                await l1.setRemoteIdentity(address, fetched);
+            }
+            return fetched;
+        },
+        getRemoteIdentities: async (addresses) => {
+            const cached = await l1.getRemoteIdentities(addresses);
+            const missing = [];
+            for (let i = 0; i < addresses.length; i += 1) {
+                if (cached[i] === null)
+                    missing.push(i);
+            }
+            if (missing.length === 0)
+                return cached;
+            const gen = generation;
+            const fetched = await backend.getRemoteIdentities(missing.map((i) => addresses[i]));
+            const coherent = gen === generation;
+            const result = cached.slice();
+            for (let j = 0; j < missing.length; j += 1) {
+                const key = fetched[j];
+                result[missing[j]] = key;
+                if (key !== null &&
+                    coherent &&
+                    (await l1.getRemoteIdentity(addresses[missing[j]])) === null) {
+                    await l1.setRemoteIdentity(addresses[missing[j]], key);
+                }
+            }
+            return result;
+        },
+        setRemoteIdentity: async (address, identityKey) => {
+            generation += 1;
+            await backend.setRemoteIdentity(address, identityKey);
+            await l1.setRemoteIdentity(address, identityKey);
+        },
+        setRemoteIdentities: async (entries) => {
+            generation += 1;
+            await backend.setRemoteIdentities(entries);
+            await l1.setRemoteIdentities(entries);
+        },
+        clear: async () => {
+            generation += 1;
+            await backend.clear();
+            await l1.clear();
+        },
+        destroy: async () => {
+            await l1.clear();
+            await backend.destroy?.();
+        }
+    };
+}

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

@@ -0,0 +1,57 @@
+import { WaPrivacyTokenMemoryStore } from '../memory/privacy-token.store.js';
+/**
+ * Read-through cache for a persistent privacy-token backend. Reuses
+ * {@link WaPrivacyTokenMemoryStore} as the bounded-LRU 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.
+ */
+export function withPrivacyTokenCache(backend, maxEntries) {
+    const l1 = new WaPrivacyTokenMemoryStore(maxEntries);
+    let generation = 0;
+    return {
+        upsert: async (record) => {
+            generation += 1;
+            await backend.upsert(record);
+            await l1.deleteByJid(record.jid);
+        },
+        upsertBatch: async (records) => {
+            generation += 1;
+            await backend.upsertBatch(records);
+            for (let i = 0; i < records.length; i += 1) {
+                await l1.deleteByJid(records[i].jid);
+            }
+        },
+        getByJid: async (jid) => {
+            const cached = await l1.getByJid(jid);
+            if (cached !== null)
+                return cached;
+            const gen = generation;
+            const fetched = await backend.getByJid(jid);
+            if (fetched !== null && gen === generation && (await l1.getByJid(jid)) === null) {
+                await l1.upsert(fetched);
+            }
+            return fetched;
+        },
+        deleteByJid: async (jid) => {
+            generation += 1;
+            const deleted = await backend.deleteByJid(jid);
+            await l1.deleteByJid(jid);
+            return deleted;
+        },
+        clear: async () => {
+            generation += 1;
+            await backend.clear();
+            await l1.clear();
+        },
+        destroy: async () => {
+            await l1.clear();
+            await backend.destroy?.();
+        }
+    };
+}

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

@@ -0,0 +1,101 @@
+import { SenderKeyMemoryStore } from '../memory/sender-key.store.js';
+/**
+ * Read-through / write-through in-process cache for a persistent sender-key
+ * backend. Reuses {@link SenderKeyMemoryStore} as the bounded-LRU L1 so the
+ * per-(group, sender) lookups repeated across a group fan-out skip the
+ * backend round-trip.
+ *
+ * Only the point reads are cached. `getGroupSenderKeyList` returns the
+ * *complete* set for a group, which a partial point cache would under-report,
+ * so it goes straight to the backend. Upserts replace the whole record (no
+ * merge), so they are write-through; the sweep deletes
+ * (`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.
+ */
+export function withSenderKeyCache(backend, maxEntries) {
+    const l1 = new SenderKeyMemoryStore({
+        maxSenderKeys: maxEntries,
+        maxSenderDistributions: maxEntries
+    });
+    let generation = 0;
+    return {
+        upsertSenderKey: async (record) => {
+            generation += 1;
+            await backend.upsertSenderKey(record);
+            await l1.upsertSenderKey(record);
+        },
+        upsertSenderKeyDistribution: async (record) => {
+            generation += 1;
+            await backend.upsertSenderKeyDistribution(record);
+            await l1.upsertSenderKeyDistribution(record);
+        },
+        upsertSenderKeyDistributions: async (records) => {
+            generation += 1;
+            await backend.upsertSenderKeyDistributions(records);
+            await l1.upsertSenderKeyDistributions(records);
+        },
+        getGroupSenderKeyList: (groupId) => backend.getGroupSenderKeyList(groupId),
+        getDeviceSenderKey: async (groupId, sender) => {
+            const cached = await l1.getDeviceSenderKey(groupId, sender);
+            if (cached !== null)
+                return cached;
+            const gen = generation;
+            const fetched = await backend.getDeviceSenderKey(groupId, sender);
+            if (fetched !== null &&
+                gen === generation &&
+                (await l1.getDeviceSenderKey(groupId, sender)) === null) {
+                await l1.upsertSenderKey(fetched);
+            }
+            return fetched;
+        },
+        getDeviceSenderKeyDistributions: async (groupId, senders) => {
+            const cached = await l1.getDeviceSenderKeyDistributions(groupId, senders);
+            const missing = [];
+            for (let i = 0; i < senders.length; i += 1) {
+                if (cached[i] === null)
+                    missing.push(i);
+            }
+            if (missing.length === 0)
+                return cached;
+            const gen = generation;
+            const fetched = await backend.getDeviceSenderKeyDistributions(groupId, missing.map((i) => senders[i]));
+            const coherent = gen === generation;
+            const result = cached.slice();
+            for (let j = 0; j < missing.length; j += 1) {
+                const record = fetched[j];
+                result[missing[j]] = record;
+                if (record !== null && coherent) {
+                    const [current] = await l1.getDeviceSenderKeyDistributions(groupId, [
+                        senders[missing[j]]
+                    ]);
+                    if (current === null)
+                        await l1.upsertSenderKeyDistribution(record);
+                }
+            }
+            return result;
+        },
+        deleteDeviceSenderKey: async (target, groupId) => {
+            generation += 1;
+            const deleted = await backend.deleteDeviceSenderKey(target, groupId);
+            await l1.deleteDeviceSenderKey(target, groupId);
+            return deleted;
+        },
+        markForgetSenderKey: async (groupId, participants) => {
+            generation += 1;
+            const deleted = await backend.markForgetSenderKey(groupId, participants);
+            await l1.markForgetSenderKey(groupId, participants);
+            return deleted;
+        },
+        clear: async () => {
+            generation += 1;
+            await backend.clear();
+            await l1.clear();
+        },
+        destroy: async () => {
+            await l1.clear();
+            await backend.destroy?.();
+        }
+    };
+}

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

@@ -0,0 +1,92 @@
+import { WaSessionMemoryStore } from '../memory/session.store.js';
+/**
+ * Read-through / write-through in-process cache for a persistent session
+ * backend. Reuses {@link WaSessionMemoryStore} as the bounded-LRU L1 so that
+ * repeated reads of the same peer on the send/recv path skip the backend
+ * round-trip.
+ *
+ * Coherence model (single process):
+ * - every mutation (set/delete/clear) writes the backend then the L1 in
+ *   lock-step and bumps a generation counter;
+ * - a read only populates the L1 when no mutation interleaved its backend
+ *   fetch (generation unchanged) and the slot is still empty, so an in-flight
+ *   read can never resurrect a concurrently deleted entry nor overwrite a
+ *   fresher concurrent write;
+ * - there is no negative caching: a miss always re-hits the backend.
+ *
+ * This cache assumes a single writer per `sessionId` (the library's
+ * connection model). Do not share one backend across processes for the same
+ * 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 });
+    let generation = 0;
+    return {
+        hasSession: async (address) => {
+            if (await l1.hasSession(address))
+                return true;
+            return backend.hasSession(address);
+        },
+        hasSessions: (addresses) => backend.hasSessions(addresses),
+        getSession: async (address) => {
+            const cached = await l1.getSession(address);
+            if (cached !== null)
+                return cached;
+            const gen = generation;
+            const fetched = await backend.getSession(address);
+            if (fetched !== null && gen === generation && (await l1.getSession(address)) === null) {
+                await l1.setSession(address, fetched);
+            }
+            return fetched;
+        },
+        getSessionsBatch: async (addresses) => {
+            const cached = await l1.getSessionsBatch(addresses);
+            const missing = [];
+            for (let i = 0; i < addresses.length; i += 1) {
+                if (cached[i] === null)
+                    missing.push(i);
+            }
+            if (missing.length === 0)
+                return cached;
+            const gen = generation;
+            const fetched = await backend.getSessionsBatch(missing.map((i) => addresses[i]));
+            const coherent = gen === generation;
+            const result = cached.slice();
+            for (let j = 0; j < missing.length; j += 1) {
+                const record = fetched[j];
+                result[missing[j]] = record;
+                if (record !== null &&
+                    coherent &&
+                    (await l1.getSession(addresses[missing[j]])) === null) {
+                    await l1.setSession(addresses[missing[j]], record);
+                }
+            }
+            return result;
+        },
+        setSession: async (address, session) => {
+            generation += 1;
+            await backend.setSession(address, session);
+            await l1.setSession(address, session);
+        },
+        setSessionsBatch: async (entries) => {
+            generation += 1;
+            await backend.setSessionsBatch(entries);
+            await l1.setSessionsBatch(entries);
+        },
+        deleteSession: async (address) => {
+            generation += 1;
+            await backend.deleteSession(address);
+            await l1.deleteSession(address);
+        },
+        clear: async () => {
+            generation += 1;
+            await backend.clear();
+            await l1.clear();
+        },
+        destroy: async () => {
+            await l1.clear();
+            await backend.destroy?.();
+        }
+    };
+}

package/dist/esm/store/contracts/group-metadata.store.js

@@ -0,0 +1 @@
+export {};