zapo-js 1.6.2 → 1.7.0

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

@@ -6,17 +6,69 @@ import { applyContextInfo, resolveSendContextInfo } from '../../message/context-
 import { injectDeviceListMetadata, resolveIcdcMeta } from '../../message/crypto/icdc.js';
 import { computePhashV2 } from '../../message/crypto/phash.js';
 import { buildReportingTokenArtifacts } from '../../message/crypto/reporting-token.js';
-import { isSendAddonCryptoMessage, isSendMediaMessage, isSendTextMessage, needsSecretPersistence, resolveButtonAddonKind, resolveDecryptFailAttr, resolveEditAttr, resolveEncMediaType, resolveMessageTypeAttr, resolveMetaAttrs, wrapAsViewOnce } from '../../message/encode/content.js';
+import { isSendAddonCryptoMessage, isSendMediaMessage, isSendTextMessage, needsSecretPersistence, resolveButtonAddonKind, resolveDecryptFailAttr, resolveEditAttr, resolveEncMediaType, resolveMessageTypeAttr, resolveMetaAttrs, unwrapMessage, wrapAsViewOnce } from '../../message/encode/content.js';
 import { wrapDeviceSentMessage } from '../../message/encode/device-sent.js';
 import { writeRandomPadMax16 } from '../../message/encode/padding.js';
 import { buildBotInvokeProtoCopy, extractInvokedBotJid, genBotMsgSecret } from '../../message/kinds/bot.js';
 import { proto } from '../../proto.js';
-import { WA_ADDRESSING_MODES, WA_DEFAULTS, WA_NACK_REASONS } from '../../protocol/constants.js';
+import { normalizeEphemeralSettingSeconds, WA_ADDRESSING_MODES, WA_DEFAULTS, WA_NACK_REASONS } from '../../protocol/constants.js';
 import { canonicalizeOwnAccountJid, isBotJid, isGroupJid, isHostedDeviceJid, isLidJid, isNewsletterJid, isUserJid, normalizeDeviceJid, normalizeRecipientJid, parseJidFull, parseSignalAddressFromJid, signalAddressKey, toUserJid } from '../../protocol/jid.js';
 import { encodeBinaryNode } from '../../transport/binary/index.js';
 import { buildButtonAddonNode, buildDirectMessageFanoutNode, buildGroupSenderKeyMessageNode, buildMetaNode } from '../../transport/node/builders/message.js';
 import { bytesToHex, TEXT_ENCODER } from '../../util/bytes.js';
 import { toError } from '../../util/primitives.js';
+/**
+ * Members a group-history bundle is addressed to. Empty for every other
+ * message, which is what keeps the restricted fanout scoped to bundles.
+ */
+function resolveGroupHistoryReceivers(message) {
+    const metadata = unwrapMessage(message).messageHistoryBundle?.messageHistoryMetadata;
+    return metadata?.historyReceivers ?? [];
+}
+/**
+ * Narrows a group's participant list to the members a group-history bundle is
+ * addressed to, plus the sender so its own devices keep a copy. Receivers are
+ * intersected with the live participant list, so a stale receiver entry cannot
+ * pull a non-member into the fanout. Any other message keeps the full list.
+ *
+ * Receivers must be written in the group's addressing mode - a PN entry for a
+ * LID-addressed group does not match and is reported through `onDropped`.
+ *
+ * @throws when no receiver matches a current member. Sending to the sender's
+ * own devices alone counts as no match: it would look like a delivered share
+ * while nobody received anything.
+ */
+export function restrictGroupHistoryTargets(message, participantUserJids, senderJid, onDropped) {
+    const receivers = resolveGroupHistoryReceivers(message);
+    if (receivers.length === 0) {
+        return participantUserJids;
+    }
+    const pending = new Set();
+    for (let index = 0; index < receivers.length; index += 1) {
+        pending.add(toUserJid(receivers[index]));
+    }
+    const senderUserJid = toUserJid(senderJid);
+    const targets = [];
+    let matchedReceivers = 0;
+    for (let index = 0; index < participantUserJids.length; index += 1) {
+        const participant = participantUserJids[index];
+        const participantUserJid = toUserJid(participant);
+        if (pending.delete(participantUserJid)) {
+            matchedReceivers += 1;
+            targets[targets.length] = participant;
+        }
+        else if (participantUserJid === senderUserJid) {
+            targets[targets.length] = participant;
+        }
+    }
+    if (pending.size > 0 && onDropped) {
+        onDropped([...pending], receivers.length);
+    }
+    if (matchedReceivers === 0) {
+        throw new Error('group history bundle resolved no receivers in the group');
+    }
+    return targets;
+}
 export class WaMessageDispatchCoordinator {
     constructor(options) {
         this.icdcDedup = new PromiseDedup();
@@ -26,6 +78,82 @@ export class WaMessageDispatchCoordinator {
         this.mobileMessageIdFormat = options.mobileMessageIdFormat ?? (() => false);
         this.serverClock = options.serverClock;
     }
+    /**
+     * Per-chat disappearing settings from the cache, falling back to the
+     * durable thread record on a cold miss and warming the cache with it. A
+     * chat with no disappearing mode is cached as expiration `0` rather than
+     * left absent, so the archive is not re-read on every send to it; the
+     * incoming writers overwrite that entry the moment the chat turns it on.
+     * A failing archive degrades the send to "no ephemeral fields" instead of
+     * rejecting it - the store is opt-in persistence, not a send dependency.
+     */
+    async resolveChatMetadata(chatJid) {
+        try {
+            const cached = await this.deps.chatMetadataStore.getChatMetadata(chatJid);
+            if (cached) {
+                return cached;
+            }
+            const thread = await this.deps.threadStore.getByJid(chatJid);
+            const expiration = thread?.ephemeralExpiration ?? 0;
+            const settingTimestamp = expiration > 0 ? thread?.ephemeralSettingTimestamp : undefined;
+            const snapshot = {
+                chatJid,
+                ephemeralExpiration: expiration,
+                ...(settingTimestamp !== undefined
+                    ? { ephemeralSettingTimestamp: settingTimestamp }
+                    : {}),
+                updatedAtMs: Date.now()
+            };
+            await this.deps.chatMetadataStore.upsertChatMetadata(snapshot);
+            return snapshot;
+        }
+        catch (error) {
+            this.deps.logger.debug('chat metadata lookup failed, sending without ephemeral fields', {
+                jid: chatJid,
+                message: toError(error).message
+            });
+            return null;
+        }
+    }
+    /**
+     * Disappearing-message fields for a send into a chat with the mode on, or
+     * `{}` when nothing resolves. Both chat kinds report initiator
+     * `CHANGED_IN_CHAT` when nothing more specific is stored; the trigger comes
+     * from the group metadata for a group and defaults to `CHAT_SETTING` for
+     * 1:1, and is omitted when a group reports none.
+     */
+    async resolveChatEphemeral(recipientJid) {
+        if (isGroupJid(recipientJid)) {
+            const settings = await this.deps.groupMetadataCache.resolveEphemeralSettings(recipientJid);
+            if (!settings) {
+                return {};
+            }
+            return {
+                expirationSeconds: settings.expirationSeconds,
+                disappearingModeInitiator: proto.DisappearingMode.Initiator.CHANGED_IN_CHAT,
+                ...(settings.trigger !== undefined
+                    ? {
+                        disappearingModeTrigger: settings.trigger
+                    }
+                    : {})
+            };
+        }
+        const chat = await this.resolveChatMetadata(recipientJid);
+        const expiration = chat?.ephemeralExpiration;
+        if (expiration === undefined || expiration <= 0) {
+            return {};
+        }
+        const stored = chat?.ephemeralSettingTimestamp;
+        const settingTimestamp = stored !== undefined ? normalizeEphemeralSettingSeconds(stored) : undefined;
+        return {
+            expirationSeconds: expiration,
+            disappearingModeInitiator: proto.DisappearingMode.Initiator.CHANGED_IN_CHAT,
+            disappearingModeTrigger: proto.DisappearingMode.Trigger.CHAT_SETTING,
+            ...(settingTimestamp !== undefined
+                ? { ephemeralSettingTimestamp: settingTimestamp }
+                : {})
+        };
+    }
     async publishMessageNode(node, options = {}) {
         this.deps.logger.trace('wa client publish message node', {
             tag: node.tag,
@@ -146,17 +274,34 @@ export class WaMessageDispatchCoordinator {
                 this.withResolvedMessageId(options)
             ]);
         }
+        const isGroupRecipient = isGroupJid(recipientJid);
+        const directRecipientJid = isGroupRecipient
+            ? recipientJid
+            : await this.resolveDirectRecipientLid(toUserJid(recipientJid));
         let optionsCtx = options.contextInfo;
         if (options.expirationSeconds !== undefined) {
             optionsCtx = { ...optionsCtx, expirationSeconds: options.expirationSeconds };
         }
-        if (isGroupJid(recipientJid) &&
-            optionsCtx?.expirationSeconds === undefined &&
-            !options.disableGroupEphemeralAutoInject) {
-            const cachedEphemeral = await this.deps.groupMetadataCache.resolveEphemeral(recipientJid);
-            if (cachedEphemeral !== null && cachedEphemeral > 0) {
-                optionsCtx = { ...optionsCtx, expirationSeconds: cachedEphemeral };
-            }
+        if (options.ephemeralSettingTimestamp !== undefined) {
+            optionsCtx = {
+                ...optionsCtx,
+                ephemeralSettingTimestamp: options.ephemeralSettingTimestamp
+            };
+        }
+        if (options.disappearingModeTrigger !== undefined) {
+            optionsCtx = {
+                ...optionsCtx,
+                disappearingModeTrigger: options.disappearingModeTrigger
+            };
+        }
+        const autoInjectDisabled = isGroupRecipient
+            ? options.disableGroupEphemeralAutoInject
+            : options.disableDirectEphemeralAutoInject;
+        if (optionsCtx?.expirationSeconds === undefined && !autoInjectDisabled) {
+            optionsCtx = {
+                ...(await this.resolveChatEphemeral(directRecipientJid)),
+                ...optionsCtx
+            };
         }
         const ctx = resolveSendContextInfo({
             contentLevel: pickContentContextInfo(content),
@@ -282,9 +427,6 @@ export class WaMessageDispatchCoordinator {
             customNodes: customNodes.length > 0 ? customNodes : undefined,
             sendOptions
         };
-        const directRecipientJid = isGroup
-            ? recipientJid
-            : await this.resolveDirectRecipientLid(toUserJid(recipientJid));
         const peerRecipientPn = isGroup
             ? undefined
             : await this.resolvePeerRecipientPn(toUserJid(recipientJid), directRecipientJid);
@@ -547,9 +689,59 @@ export class WaMessageDispatchCoordinator {
     async mutateGroupMetadataCacheFromGroupEvent(event) {
         await this.deps.groupMetadataCache.mutateFromGroupEvent(event);
     }
-    // noop for now
+    /**
+     * Splits a group's members into the ones a history bundle is being shared
+     * with and the rest, normalizing everything to the group's addressing mode
+     * so the receiver list written into the proto matches what the fanout can
+     * actually resolve. This account is excluded from both lists.
+     *
+     * Requested JIDs that are not current members come back in `unknownJids`
+     * instead of being silently dropped - sharing history with a non-member is
+     * a caller mistake worth surfacing.
+     */
+    async resolveGroupHistoryAudience(groupJid, requestedJids) {
+        const participants = await this.deps.groupMetadataCache.resolveParticipantUsers(groupJid);
+        const meJid = this.requireCurrentMeJid('shareGroupHistory');
+        const addressingMode = this.resolveGroupAddressingMode(participants, groupJid);
+        const meUserJid = toUserJid(this.resolveSenderForAddressingMode(addressingMode, meJid));
+        const pending = new Set();
+        for (let index = 0; index < requestedJids.length; index += 1) {
+            pending.add(toUserJid(normalizeRecipientJid(requestedJids[index])));
+        }
+        const historyReceivers = [];
+        const nonHistoryReceivers = [];
+        for (let index = 0; index < participants.length; index += 1) {
+            const participantUserJid = toUserJid(participants[index]);
+            if (participantUserJid === meUserJid) {
+                continue;
+            }
+            if (pending.delete(participantUserJid)) {
+                historyReceivers[historyReceivers.length] = participantUserJid;
+            }
+            else {
+                nonHistoryReceivers[nonHistoryReceivers.length] = participantUserJid;
+            }
+        }
+        const requestedSelf = pending.delete(meUserJid);
+        const unknownJids = [];
+        for (const jid of pending) {
+            unknownJids[unknownJids.length] = jid;
+        }
+        return {
+            historyReceivers,
+            nonHistoryReceivers,
+            unknownJids,
+            requestedSelf,
+            addressingMode
+        };
+    }
+    /**
+     * A group-history bundle goes to the members named in `historyReceivers`
+     * rather than to the whole group, so it takes the per-device direct fanout
+     * instead of the group sender key.
+     */
     shouldUseGroupDirectPath(message) {
-        return false;
+        return resolveGroupHistoryReceivers(message).length > 0;
     }
     async publishGroupDirectMessage(groupJid, envelope, retryContext = {}) {
         const { message, plaintext, type, edit, mediatype, sendOptions } = envelope;
@@ -559,8 +751,16 @@ export class WaMessageDispatchCoordinator {
             : await this.deps.groupMetadataCache.resolveParticipantUsers(groupJid);
         const addressingMode = retryContext.forceAddressingMode ??
             this.resolveGroupAddressingMode(participantUserJids, groupJid);
-        const senderForPhash = this.resolveSenderForAddressingMode(addressingMode, meJid);
-        const fanoutDeviceJids = await this.deps.fanoutResolver.resolveGroupParticipantDeviceJids(participantUserJids);
+        const senderJid = this.resolveSenderForAddressingMode(addressingMode, meJid);
+        const targetUserJids = restrictGroupHistoryTargets(message, participantUserJids, senderJid, (droppedJids, totalExpected) => {
+            this.deps.logger.warn('group history receivers missing from the participant list', {
+                groupJid,
+                droppedCount: droppedJids.length,
+                totalExpected,
+                sample: droppedJids.slice(0, 3)
+            });
+        });
+        const fanoutDeviceJids = await this.deps.fanoutResolver.resolveGroupParticipantDeviceJids(targetUserJids);
         if (fanoutDeviceJids.length === 0) {
             throw new Error('group direct send resolved no target devices');
         }
@@ -615,22 +815,10 @@ export class WaMessageDispatchCoordinator {
                 break;
             }
         }
-        const phashTargets = new Array(resolvedFanoutTargets.length + 1);
-        let phashTargetCount = 0;
-        for (let index = 0; index < resolvedFanoutTargets.length; index += 1) {
-            const candidate = resolvedFanoutTargets[index].jid;
-            if (isHostedDeviceJid(candidate))
-                continue;
-            phashTargets[phashTargetCount] = candidate;
-            phashTargetCount += 1;
-        }
-        phashTargets[phashTargetCount] = senderForPhash;
-        phashTargets.length = phashTargetCount + 1;
-        const localPhash = computePhashV2(phashTargets);
         const reportingArtifacts = await this.tryBuildReportingTokenArtifacts({
             message,
             stanzaId: sendOptions.id,
-            senderUserJid: toUserJid(senderForPhash),
+            senderUserJid: toUserJid(senderJid),
             remoteJid: groupJid,
             context: 'group_direct'
         });
@@ -642,7 +830,6 @@ export class WaMessageDispatchCoordinator {
             type,
             id: sendOptions.id,
             edit,
-            phash: localPhash,
             addressingMode,
             participants,
             deviceIdentity: shouldAttachDeviceIdentity
@@ -668,7 +855,7 @@ export class WaMessageDispatchCoordinator {
         const ackError = result.ack.error;
         const serverPhash = result.ack.phash;
         const serverAddressingMode = result.ack.addressingMode;
-        const hasPhashMismatch = !!serverPhash && serverPhash !== localPhash;
+        const hasPhashMismatch = !!serverPhash;
         const hasAddressingMismatch = !!serverAddressingMode && serverAddressingMode !== addressingMode;
         const hasAddressingError = ackError === WA_NACK_REASONS.STALE_GROUP_ADDRESSING_MODE;
         if (!retryContext.retried &&
@@ -676,7 +863,6 @@ export class WaMessageDispatchCoordinator {
             this.deps.logger.warn('group direct publish acknowledged with mismatch metadata', {
                 id: result.id,
                 groupJid,
-                localPhash,
                 serverPhash,
                 localAddressingMode: addressingMode,
                 serverAddressingMode,

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

@@ -1,91 +1,12 @@
+import { parseBlocklist, parseDisallowedList, parseDisallowedListUpdate, parsePrivacyCategoryDhash, parsePrivacySettings } from '../events/privacy.js';
+import { PromiseDedup } from '../../infra/perf/PromiseDedup.js';
+import { WA_DEFAULTS } from '../../protocol/defaults.js';
 import { isLidJid, isUserJid, normalizeRecipientJid } from '../../protocol/jid.js';
-import { WA_NODE_TAGS } from '../../protocol/nodes.js';
-import { WA_PRIVACY_CATEGORY_TO_SETTING, WA_PRIVACY_SETTING_TO_CATEGORY, WA_PRIVACY_TAGS, WA_PRIVACY_VALUES } from '../../protocol/privacy.js';
-import { buildBlocklistBlockIq, buildBlocklistUnblockIq, buildGetBlocklistIq, buildGetPrivacyDisallowedListIq, buildGetPrivacySettingsIq, buildSetPrivacyCategoryIq } from '../../transport/node/builders/privacy.js';
-import { findNodeChild, getNodeChildren, getNodeChildrenByTag } from '../../transport/node/helpers.js';
-import { assertIqResult } from '../../transport/node/query.js';
-const IGNORED_SERVER_CATEGORIES = new Set([
-    'pix',
-    'linked_profiles',
-    'stickers',
-    'dependentaccountmessages',
-    'cover_photo',
-    'dependent_account_calling',
-    'groupcreation'
-]);
-const VALID_PRIVACY_VALUES = new Set(Object.values(WA_PRIVACY_VALUES));
-function isValidPrivacyValue(value) {
-    return value !== WA_PRIVACY_VALUES.ERROR && VALID_PRIVACY_VALUES.has(value);
-}
-function parsePrivacySettings(result) {
-    const privacyNode = findNodeChild(result, WA_NODE_TAGS.PRIVACY);
-    if (!privacyNode) {
-        return {};
-    }
-    const settings = {};
-    const categories = getNodeChildrenByTag(privacyNode, WA_PRIVACY_TAGS.CATEGORY);
-    for (let i = 0; i < categories.length; i += 1) {
-        const node = categories[i];
-        const name = node.attrs.name;
-        const value = node.attrs.value;
-        if (!name || !value) {
-            continue;
-        }
-        if (IGNORED_SERVER_CATEGORIES.has(name)) {
-            continue;
-        }
-        if (!isValidPrivacyValue(value)) {
-            continue;
-        }
-        const settingName = WA_PRIVACY_CATEGORY_TO_SETTING[name];
-        if (settingName) {
-            settings[settingName] = value;
-        }
-    }
-    return settings;
-}
-function parseDisallowedList(result) {
-    const privacyNode = findNodeChild(result, WA_NODE_TAGS.PRIVACY);
-    if (!privacyNode) {
-        return { jids: [] };
-    }
-    const listNode = findNodeChild(privacyNode, WA_PRIVACY_TAGS.LIST);
-    if (!listNode) {
-        return { jids: [] };
-    }
-    const dhash = listNode.attrs.dhash;
-    const userNodes = getNodeChildrenByTag(listNode, WA_PRIVACY_TAGS.USER);
-    const jids = new Array(userNodes.length);
-    let jidsCount = 0;
-    for (let i = 0; i < userNodes.length; i += 1) {
-        const jid = userNodes[i].attrs.jid;
-        if (jid) {
-            jids[jidsCount] = jid;
-            jidsCount += 1;
-        }
-    }
-    jids.length = jidsCount;
-    return { jids, dhash };
-}
-function parseBlocklist(result) {
-    const listNode = findNodeChild(result, WA_NODE_TAGS.LIST);
-    if (!listNode) {
-        return { jids: [] };
-    }
-    const dhash = listNode.attrs.dhash;
-    const itemNodes = getNodeChildren(listNode);
-    const jids = new Array(itemNodes.length);
-    let jidsCount = 0;
-    for (let i = 0; i < itemNodes.length; i += 1) {
-        const jid = itemNodes[i].attrs.jid;
-        if (jid) {
-            jids[jidsCount] = jid;
-            jidsCount += 1;
-        }
-    }
-    jids.length = jidsCount;
-    return { jids, dhash };
-}
+import { WA_IQ_TYPES, WA_NODE_TAGS } from '../../protocol/nodes.js';
+import { WA_PRIVACY_ACCOUNT_SYNC_DISALLOWED_LISTS, WA_PRIVACY_LIST_ACTIONS, WA_PRIVACY_SETTING_TO_CATEGORY } from '../../protocol/privacy.js';
+import { buildBlocklistBlockIq, buildBlocklistUnblockIq, buildGetBlocklistIq, buildGetPrivacyDisallowedListIq, buildGetPrivacySettingsIq, buildSetPrivacyCategoryIq, buildSetPrivacyDisallowedListIq } from '../../transport/node/builders/privacy.js';
+import { assertIqResult, parseIqError } from '../../transport/node/query.js';
+import { toError } from '../../util/primitives.js';
 /**
  * Resolves a blocklist input into both addressing forms via
  * `resolveUserJidPair` (device-list cache first, usync fallback for phone
@@ -103,9 +24,111 @@ async function resolveBlocklistTarget(options, jid) {
     }
     return { lidJid: null, pnJid: pair.pnJid ?? normalized };
 }
+const ACCOUNT_SYNC_REFRESH_KEY = 'account-sync';
+/**
+ * A `409` on a disallowed-list write means the `dhash` we sent no longer
+ * matches the server's: another device changed the list in between.
+ */
+function isStaleDhashResult(node) {
+    if (node.tag !== WA_NODE_TAGS.IQ || node.attrs.type === WA_IQ_TYPES.RESULT) {
+        return false;
+    }
+    const error = parseIqError(node);
+    return error.numericCode === 409 || error.code === '409';
+}
+/**
+ * Resolves a disallowed-list input into `<user>` entries. Unlike the blocklist
+ * the server takes both actions in one stanza, so add/remove are resolved
+ * together and keep their relative order.
+ */
+async function resolveDisallowedListEntries(options, input) {
+    const entries = [];
+    const actions = [
+        { action: WA_PRIVACY_LIST_ACTIONS.ADD, jids: input.add ?? [] },
+        { action: WA_PRIVACY_LIST_ACTIONS.REMOVE, jids: input.remove ?? [] }
+    ];
+    for (const { action, jids } of actions) {
+        for (const jid of jids) {
+            const target = await resolveBlocklistTarget(options, jid);
+            entries.push({ action, lidJid: target.lidJid, pnJid: target.pnJid });
+        }
+    }
+    if (entries.length === 0) {
+        throw new Error('setDisallowedList requires at least one add/remove entry');
+    }
+    return entries;
+}
 /** Builds a {@link WaPrivacyCoordinator} backed by the given IQ query function. */
 export function createPrivacyCoordinator(options) {
     const { queryWithContext } = options;
+    const usesLidAddressing = () => options.getSelfLid() !== null;
+    let refreshTimer = null;
+    let refreshStopped = false;
+    let activeRefresh = null;
+    const refreshDedup = new PromiseDedup();
+    const queryDisallowedList = async (category) => {
+        const node = buildGetPrivacyDisallowedListIq(category, usesLidAddressing());
+        const result = await queryWithContext('privacy.getDisallowedList', node, undefined, {
+            category
+        });
+        assertIqResult(result, 'privacy.getDisallowedList');
+        return result;
+    };
+    const readDisallowedList = async (category) => parseDisallowedList(await queryDisallowedList(category));
+    const runAccountSyncRefresh = async () => {
+        const settingsNode = await queryWithContext('privacy.getSettings', buildGetPrivacySettingsIq());
+        assertIqResult(settingsNode, 'privacy.getSettings');
+        const listNodes = await Promise.all(WA_PRIVACY_ACCOUNT_SYNC_DISALLOWED_LISTS.map(async (setting) => ({
+            setting,
+            node: await queryDisallowedList(WA_PRIVACY_SETTING_TO_CATEGORY[setting])
+        })));
+        const disallowedLists = [];
+        for (const { setting, node } of listNodes) {
+            const update = parseDisallowedListUpdate(node);
+            if (update) {
+                disallowedLists.push({ setting, ...update });
+            }
+        }
+        const result = {
+            settings: parsePrivacySettings(settingsNode),
+            disallowedLists
+        };
+        options.emitPrivacy(result);
+        return result;
+    };
+    /**
+     * Joins a refresh already in flight instead of racing it, so concurrent
+     * callers share one round of queries and one emit.
+     */
+    const dedupedRefresh = () => {
+        const running = refreshDedup.run(ACCOUNT_SYNC_REFRESH_KEY, runAccountSyncRefresh);
+        activeRefresh = running;
+        return running;
+    };
+    /**
+     * Refresh for a change the server just announced. It must not join a
+     * refresh already in flight: that one's queries went out before the
+     * change landed, so joining it would emit a snapshot without the new
+     * value and nothing would refetch. Waiting for it first guarantees a read
+     * issued after the notification.
+     */
+    const followUpRefresh = async () => {
+        if (refreshStopped) {
+            return;
+        }
+        await activeRefresh?.catch(() => undefined);
+        if (refreshStopped) {
+            return;
+        }
+        await dedupedRefresh();
+    };
+    const writeDisallowedList = async (category, entries, dhash) => {
+        const node = buildSetPrivacyDisallowedListIq(category, entries, dhash, usesLidAddressing());
+        return queryWithContext('privacy.setDisallowedList', node, undefined, {
+            category,
+            entries: entries.length
+        });
+    };
     return {
         getPrivacySettings: async () => {
             const node = buildGetPrivacySettingsIq();
@@ -121,15 +144,43 @@ export function createPrivacyCoordinator(options) {
                 value
             });
             assertIqResult(result, 'privacy.setSetting');
+            return parsePrivacyCategoryDhash(result, category);
         },
-        getDisallowedList: async (setting) => {
+        getDisallowedList: async (setting) => readDisallowedList(WA_PRIVACY_SETTING_TO_CATEGORY[setting]),
+        setDisallowedList: async (setting, input) => {
             const category = WA_PRIVACY_SETTING_TO_CATEGORY[setting];
-            const node = buildGetPrivacyDisallowedListIq(category);
-            const result = await queryWithContext('privacy.getDisallowedList', node, undefined, {
-                category
-            });
-            assertIqResult(result, 'privacy.getDisallowedList');
-            return parseDisallowedList(result);
+            const entries = await resolveDisallowedListEntries(options, input);
+            const current = await readDisallowedList(category);
+            let result = await writeDisallowedList(category, entries, current.dhash ?? null);
+            if (isStaleDhashResult(result)) {
+                const refreshed = await readDisallowedList(category);
+                result = await writeDisallowedList(category, entries, refreshed.dhash ?? null);
+            }
+            assertIqResult(result, 'privacy.setDisallowedList');
+            return parsePrivacyCategoryDhash(result, category);
+        },
+        refreshFromAccountSync: () => dedupedRefresh(),
+        scheduleAccountSyncRefresh: () => {
+            refreshStopped = false;
+            if (refreshTimer !== null) {
+                clearTimeout(refreshTimer);
+            }
+            refreshTimer = setTimeout(() => {
+                refreshTimer = null;
+                void followUpRefresh().catch((error) => {
+                    options.logger.warn('account_sync privacy refresh failed', {
+                        message: toError(error).message
+                    });
+                });
+            }, WA_DEFAULTS.PRIVACY_ACCOUNT_SYNC_DEBOUNCE_MS);
+            refreshTimer.unref?.();
+        },
+        stopAccountSyncRefresh: () => {
+            refreshStopped = true;
+            if (refreshTimer !== null) {
+                clearTimeout(refreshTimer);
+                refreshTimer = null;
+            }
         },
         getBlocklist: async () => {
             const node = buildGetBlocklistIq();