zapo-js 1.1.1 → 1.1.3

package/dist/appstate/sync/WaAppStateSyncClient.d.ts

@@ -25,7 +25,12 @@ interface WaAppStateSyncClientOptions {
     readonly defaultTimeoutMs?: number;
     readonly onMissingKeys?: (event: WaAppStateMissingKeysEvent) => Promise<void>;
     readonly skipMacVerification?: boolean;
-    readonly mobilePrimary?: boolean;
+    /**
+     * Resolved per sync operation (post-connect, after credentials load) so a
+     * registered mobile-primary session reconnecting without an explicit
+     * `mobileTransport` option still drives the primary-authoritative sync path.
+     */
+    readonly mobilePrimary?: () => boolean;
     readonly isOwnAccountDevice?: (deviceJid: string) => boolean;
     readonly sendKeyShare?: (toDeviceJid: string, keys: readonly WaAppStateSyncKey[], missingKeyIds: readonly Uint8Array[]) => Promise<void>;
     readonly triggerSync?: () => Promise<void>;
@@ -55,6 +60,11 @@ export declare class WaAppStateSyncClient {
     /**
      * Returns the active app-state sync key, generating and persisting a new
      * one when the store is empty (used during initial setup).
+     *
+     * The key id mirrors the primary device layout: 2 big-endian bytes of
+     * device id followed by a 4 big-endian byte epoch. `keyEpoch` and
+     * `pickActiveSyncKey` read that structure, so a shorter id would make the
+     * generated key invisible to active-key selection.
      */
     ensureInitialSyncKey(): Promise<WaAppStateSyncKey>;
     /** Imports peer-shared sync keys into the store; returns the count actually added. */

package/dist/appstate/sync/WaAppStateSyncClient.js

@@ -38,20 +38,33 @@ class WaAppStateSyncClient {
         this.sendKeyShare = options.sendKeyShare;
         this.triggerSync = options.triggerSync;
         this.crypto = new WaAppStateCrypto_1.WaAppStateCrypto(undefined, options.skipMacVerification === true);
-        this.mobilePrimary = options.mobilePrimary ?? false;
+        this.mobilePrimary = options.mobilePrimary ?? (() => false);
         this.syncContext = null;
         this.syncPromise = null;
     }
     /**
      * Returns the active app-state sync key, generating and persisting a new
      * one when the store is empty (used during initial setup).
+     *
+     * The key id mirrors the primary device layout: 2 big-endian bytes of
+     * device id followed by a 4 big-endian byte epoch. `keyEpoch` and
+     * `pickActiveSyncKey` read that structure, so a shorter id would make the
+     * generated key invisible to active-key selection.
      */
     async ensureInitialSyncKey() {
         const existing = await this.store.getActiveSyncKey();
         if (existing) {
             return existing;
         }
-        const keyIdBytes = await (0, _crypto_1.randomBytesAsync)(2);
+        const deviceId = this.resolveDeviceIndex() ?? 0;
+        const epoch = await (0, _crypto_1.randomIntAsync)(1, 65537);
+        const keyIdBytes = new Uint8Array(6);
+        keyIdBytes[0] = (deviceId >>> 8) & 0xff;
+        keyIdBytes[1] = deviceId & 0xff;
+        keyIdBytes[2] = (epoch >>> 24) & 0xff;
+        keyIdBytes[3] = (epoch >>> 16) & 0xff;
+        keyIdBytes[4] = (epoch >>> 8) & 0xff;
+        keyIdBytes[5] = epoch & 0xff;
         const keyData = await (0, _crypto_1.randomBytesAsync)(32);
         const rawId = await (0, _crypto_1.randomIntAsync)(0, 4294967295);
         const key = {
@@ -64,6 +77,7 @@ class WaAppStateSyncClient {
         this.crypto.clearCache();
         this.logger.info('app-state initial sync key generated (mobile primary)', {
             keyId: (0, bytes_1.bytesToHex)(keyIdBytes),
+            epoch,
             rawId
         });
         return key;
@@ -389,17 +403,18 @@ class WaAppStateSyncClient {
     async buildCollectionSyncRequest(collection, pendingByCollection, activeSyncKey) {
         const collectionState = await this.getCollectionState(collection);
         const hasPersistedState = collectionState.initialized;
+        const requestSnapshot = !this.mobilePrimary() && !hasPersistedState;
         const attrs = {
             name: collection,
             version: String(hasPersistedState ? collectionState.version : constants_1.APP_STATE_DEFAULT_COLLECTION_VERSION),
-            return_snapshot: hasPersistedState ? 'false' : 'true'
+            return_snapshot: requestSnapshot ? 'true' : 'false'
         };
         const children = [];
         const pendingMutations = pendingByCollection.get(collection) ?? [];
         let outgoingContext;
         let skippedUpload = false;
         if (pendingMutations.length > 0) {
-            if (!hasPersistedState) {
+            if (!hasPersistedState && !this.mobilePrimary()) {
                 skippedUpload = true;
                 this.logger.debug('app-state skipped outgoing patch upload until snapshot bootstrap', {
                     collection,
@@ -438,7 +453,7 @@ class WaAppStateSyncClient {
             content: [
                 {
                     tag: constants_2.WA_NODE_TAGS.SYNC,
-                    attrs: this.mobilePrimary ? { data_namespace: '3' } : {},
+                    attrs: this.mobilePrimary() ? { data_namespace: '3' } : {},
                     content: collectionNodes
                 }
             ]
@@ -473,20 +488,19 @@ class WaAppStateSyncClient {
             return this.createCollectionOutcome(collection, payload.state, payload.version);
         }
         const pendingMutationsCount = pendingByCollection.get(collection)?.length ?? 0;
-        if (payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT ||
-            payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT_HAS_MORE) {
+        const isConflict = payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT ||
+            payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT_HAS_MORE;
+        if (isConflict) {
             shouldRefetch =
                 payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT_HAS_MORE ||
                     pendingMutationsCount > 0;
-            return this.createCollectionOutcome(collection, payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT
-                ? pendingMutationsCount > 0
-                    ? constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT
-                    : constants_2.WA_APP_STATE_COLLECTION_STATES.SUCCESS
-                : payload.state, payload.version, shouldRefetch);
         }
         try {
             let appliedMutations = [];
-            if (payload.snapshotReference) {
+            if (payload.snapshotReference && this.mobilePrimary()) {
+                collectionLogger.debug('app-state ignoring server snapshot on primary device');
+            }
+            else if (payload.snapshotReference) {
                 const downloader = options.downloadExternalBlob;
                 if (!downloader) {
                     throw new Error(`snapshot for ${payload.collection} requires external blob downloader`);
@@ -525,12 +539,19 @@ class WaAppStateSyncClient {
                     payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.SUCCESS_HAS_MORE ||
                     (payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.SUCCESS &&
                         skippedUploadCollections.has(collection));
+            const resolvedState = !isConflict
+                ? payload.state
+                : payload.state === constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT
+                    ? pendingMutationsCount > 0
+                        ? constants_2.WA_APP_STATE_COLLECTION_STATES.CONFLICT
+                        : constants_2.WA_APP_STATE_COLLECTION_STATES.SUCCESS
+                    : payload.state;
             collectionLogger.debug('app-state collection processed', {
-                state: payload.state,
+                state: resolvedState,
                 version: payload.version,
                 appliedMutations: appliedMutations.length
             });
-            return this.createCollectionOutcome(collection, payload.state, payload.version, shouldRefetch, collectionStateChanged, appliedMutations);
+            return this.createCollectionOutcome(collection, resolvedState, payload.version, shouldRefetch, collectionStateChanged, appliedMutations);
         }
         catch (error) {
             if (error instanceof WaAppStateMissingKeyError) {

package/dist/auth/credentials-flow.js

@@ -35,6 +35,8 @@ async function loadOrCreateCredentials(args) {
     }
     await restoreSignalStore(args.signalStore, args.preKeyStore, existing);
     args.logger.trace('auth credentials restored into signal store');
+    // A mobile primary has no self-signed device-identity and no key-index-list:
+    // both are companion-only (set at pairing). Do not re-add them here.
     return existing;
 }
 async function persistCredentials(args, credentials) {
@@ -134,7 +136,7 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
         noise: {
             clientStaticKeyPair: credentials.noiseKeyPair,
             isRegistered: registered,
-            serverStaticKey: credentials.serverStaticKey,
+            serverStaticKey: registered ? credentials.serverStaticKey : undefined,
             routingInfo: credentials.routingInfo,
             trustedRootCa: clientOptions.noiseTrustedRootCa,
             verifyCertificateChain: clientOptions.disableNoiseCertificateChainVerification

package/dist/client/WaClientFactory.js

@@ -214,7 +214,7 @@ function buildWaClientDependencies(input) {
         logger,
         defaultTimeoutMs: options.nodeQueryTimeoutMs,
         hostDomain: constants_1.WA_DEFAULTS.HOST_DOMAIN,
-        mobileIqIdFormat: options.mobileTransport !== undefined
+        mobileIqIdFormat: () => isMobilePrimary()
     });
     const keepAlive = new WaKeepAlive_1.WaKeepAlive({
         logger,
@@ -356,6 +356,7 @@ function buildWaClientDependencies(input) {
         }
     });
     const getCurrentCredentials = authClient.getCurrentCredentials.bind(authClient);
+    const isMobilePrimary = () => options.mobileTransport !== undefined || Boolean(getCurrentCredentials()?.deviceInfo);
     const groupCoordinator = (0, WaGroupCoordinator_1.createGroupCoordinator)({
         queryWithContext: runtime.queryWithContext,
         mexSocket: { query: runtime.query }
@@ -481,12 +482,13 @@ function buildWaClientDependencies(input) {
             additionalAttributes: sendOptions.additionalAttributes
         }),
         getIcdcHashLength: () => abPropsCoordinator.getConfigValue('md_icdc_hash_length'),
-        mobileMessageIdFormat: options.mobileTransport !== undefined,
+        mobileMessageIdFormat: isMobilePrimary,
         serverClock
     });
     const presenceCoordinator = (0, WaPresenceCoordinator_1.createPresenceCoordinator)({
         sendNode: (node) => nodeOrchestrator.sendNode(node, false),
-        getCurrentCredentials
+        getCurrentCredentials,
+        resolvePrivacyTokenNode: (jid) => trustedContactToken.resolveReceiverTokenNode(jid)
     });
     const peerDataOperation = (0, peer_data_operation_1.createPeerDataOperationRequester)({
         logger,
@@ -521,12 +523,15 @@ function buildWaClientDependencies(input) {
         sendNode: runtime.sendNode,
         getCurrentCredentials,
         resolveUserIcdc: (userJid) => messageDispatch.resolveUserIcdc(userJid),
+        resolvePrivacyTokenNode: (recipientJid) => trustedContactToken.resolveTokenForMessage(recipientJid),
+        // Placeholder resend asks the primary phone (a peer) for the plaintext.
         peerDataOperation,
         emitIncomingMessage: (event) => {
             void runtime
                 .handleIncomingMessageEvent(event)
                 .catch((err) => runtime.handleError((0, primitives_1.toError)(err)));
-        }
+        },
+        isMobilePrimary
     });
     const botCoordinator = (0, WaBotCoordinator_1.createBotCoordinator)({
         logger,
@@ -550,20 +555,30 @@ function buildWaClientDependencies(input) {
             await messageDispatch.requestAppStateSyncKeys(keyIds);
         },
         skipMacVerification: options.dangerous?.disableAppStateMacVerification,
-        mobilePrimary: options.mobileTransport !== undefined,
+        mobilePrimary: isMobilePrimary,
         isOwnAccountDevice: (deviceJid) => {
             const credentials = getCurrentCredentials();
             if (!credentials)
                 return false;
-            const candidateUser = (0, jid_1.toUserJid)(deviceJid);
-            return ((!!credentials.meJid && (0, jid_1.toUserJid)(credentials.meJid) === candidateUser) ||
-                (!!credentials.meLid && (0, jid_1.toUserJid)(credentials.meLid) === candidateUser));
+            return (0, jid_1.isOwnAccountJid)(deviceJid, credentials.meJid, credentials.meLid);
         },
         sendKeyShare: (toDeviceJid, keys, missingKeyIds) => messageDispatch.sendAppStateSyncKeyShare(toDeviceJid, keys, missingKeyIds),
         triggerSync: async () => {
             await runtime.syncAppState();
         }
     });
+    // Persists a pushName change and re-broadcasts presence carrying it (how the
+    // name reaches peers on primary connections). No-op when unchanged, which
+    // also collapses the app-state echo of our own SettingPushName write.
+    const applyOwnPushName = async (name) => {
+        if (getCurrentCredentials()?.meDisplayName === name) {
+            return;
+        }
+        await authClient.persistSuccessAttributes({ meDisplayName: name });
+        if (connectionManager?.isConnected()) {
+            await presenceCoordinator.send();
+        }
+    };
     const appStateMutations = new WaAppStateMutationCoordinator_1.WaAppStateMutationCoordinator({
         logger,
         messageStore: sessionStore.messages,
@@ -574,7 +589,12 @@ function buildWaClientDependencies(input) {
         emitSnapshotMutations: options.chatEvents?.emitSnapshotMutations === true,
         emitMutation: (event) => runtime.emitEvent('mutation', event),
         nctSaltSink: (salt) => trustedContactToken.handleNctSaltSync(salt),
-        contactSink: runtime.persistContact
+        contactSink: runtime.persistContact,
+        pushNameSink: (name) => {
+            void applyOwnPushName(name).catch((error) => logger.debug('apply own pushName from app-state sync failed', {
+                message: (0, primitives_1.toError)(error).message
+            }));
+        }
     });
     const profileCoordinator = (0, WaProfileCoordinator_1.createProfileCoordinator)({
         queryWithContext: runtime.queryWithContext,
@@ -582,6 +602,8 @@ function buildWaClientDependencies(input) {
         mexSocket: { query: runtime.query },
         queryLidsByPhoneJids: (phoneJids) => signalDeviceSync.queryLidsByPhoneJids(phoneJids),
         mutations: appStateMutations,
+        applyOwnPushName,
+        resolvePrivacyTokenNode: (jid) => trustedContactToken.resolveReceiverTokenNode(jid),
         logger
     });
     const statusCoordinator = (0, WaStatusCoordinator_1.createStatusCoordinator)({
@@ -662,6 +684,7 @@ function buildWaClientDependencies(input) {
         logger,
         sendNode: runtime.sendNode,
         getMeJid: () => getCurrentCredentials()?.meJid,
+        getMeLid: () => getCurrentCredentials()?.meLid,
         signalProtocol,
         senderKeyManager,
         onDecryptFailure: (context, error) => retryCoordinator.onDecryptFailure(context, error),
@@ -979,7 +1002,7 @@ function buildWaClientDependencies(input) {
             abPropsCoordinator,
             markOnlineOnConnect: options.markOnlineOnConnect ?? false
         }),
-        mobilePrimary: options.mobileTransport !== undefined,
+        mobilePrimary: isMobilePrimary,
         appStateSync
     });
     const lowLevelCoordinator = (0, WaLowLevelCoordinator_1.createLowLevelCoordinator)({

package/dist/client/connection/WaConnectionManager.js

@@ -249,6 +249,9 @@ class WaConnectionManager {
             if (!serverStaticKey) {
                 this.logger.trace('no server static key available to persist');
             }
+            else if (!credentials.meJid) {
+                this.logger.trace('skipping server static key persist while unregistered');
+            }
             else {
                 await this.authClient.persistServerStaticKey(serverStaticKey);
                 this.assertLifecycleCurrent(lifecycleGeneration, 'start comms');

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

@@ -42,6 +42,12 @@ interface WaAppStateMutationCoordinatorOptions {
      * bootstrapped at pair-time regardless of `emitSnapshotMutations`.
      */
     readonly contactSink?: (record: WaStoredContactRecord) => void;
+    /**
+     * Sink for applied `SettingPushName` mutations (the account's own display
+     * name). Invoked on every winning mutation including snapshot ones, so the
+     * local display name is bootstrapped at pair-time.
+     */
+    readonly pushNameSink?: (name: string) => void;
 }
 export interface WaSetStatusPrivacyInput {
     readonly mode: StatusDistributionModeKey | StatusDistributionMode;
@@ -76,6 +82,7 @@ export declare class WaAppStateMutationCoordinator {
     private readonly emitSnapshotMutations;
     private readonly nctSaltSink?;
     private readonly contactSink?;
+    private readonly pushNameSink?;
     private readonly pendingMutations;
     private flushPromise;
     constructor(options: WaAppStateMutationCoordinatorOptions);
@@ -96,6 +103,7 @@ export declare class WaAppStateMutationCoordinator {
     emitEventsFromSyncResult(syncResult: WaAppStateSyncResult): void;
     private handleNctSaltMutation;
     private handleContactMutation;
+    private handlePushNameMutation;
     /**
      * Mutes or unmutes a chat. `muteEndTimestampMs` is required when
      * `muted` is `true` and must be a non-negative safe-integer epoch.

package/dist/client/coordinators/WaAppStateMutationCoordinator.js

@@ -183,6 +183,7 @@ class WaAppStateMutationCoordinator {
         this.emitSnapshotMutations = options.emitSnapshotMutations === true;
         this.nctSaltSink = options.nctSaltSink;
         this.contactSink = options.contactSink;
+        this.pushNameSink = options.pushNameSink;
         this.pendingMutations = new Map();
         this.flushPromise = null;
     }
@@ -230,11 +231,10 @@ class WaAppStateMutationCoordinator {
     emitEventsFromSyncResult(syncResult) {
         for (const collectionResult of syncResult.collections) {
             const mutations = collectionResult.mutations ?? [];
-            // Persistence sinks (contact store, ...): run on the last-wins
-            // mutation per key INCLUDING snapshot sources, so pair-time
-            // bootstrap of the address book always lands in the store even
-            // when public events are suppressed for snapshot mutations.
-            if (this.contactSink) {
+            // Persistence sinks (contact store, own pushName): run on the
+            // last-wins mutation per key INCLUDING snapshot sources, so
+            // pair-time bootstrap lands even when snapshot events are suppressed.
+            if (this.contactSink || this.pushNameSink) {
                 const sinkLastIndex = new Map();
                 for (let i = 0; i < mutations.length; i += 1) {
                     const m = mutations[i];
@@ -255,6 +255,16 @@ class WaAppStateMutationCoordinator {
                             message: (0, primitives_1.toError)(error).message
                         });
                     }
+                    try {
+                        this.handlePushNameMutation(m);
+                    }
+                    catch (error) {
+                        this.logger.debug('pushName sink failed', {
+                            collection: m.collection,
+                            index: m.index,
+                            message: (0, primitives_1.toError)(error).message
+                        });
+                    }
                 }
             }
             const lastMutationIndexByKey = new Map();
@@ -359,6 +369,20 @@ class WaAppStateMutationCoordinator {
             lastUpdatedMs
         });
     }
+    handlePushNameMutation(mutation) {
+        if (!this.pushNameSink)
+            return;
+        // A `set` under the literal index ["setting_pushName"]; cheap reject
+        // before reading the value.
+        if (mutation.operation !== 'set')
+            return;
+        if (!mutation.index.includes('setting_pushName'))
+            return;
+        const name = mutation.value?.pushNameSetting?.name;
+        if (typeof name !== 'string')
+            return;
+        this.pushNameSink(name);
+    }
     /**
      * Mutes or unmutes a chat. `muteEndTimestampMs` is required when
      * `muted` is `true` and must be a non-negative safe-integer epoch.

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

@@ -50,7 +50,12 @@ interface WaMessageDispatchCoordinatorOptions {
     readonly onDirectMessageSent: (recipientJid: string) => void;
     readonly sendNewsletterMessage?: (newsletterJid: string, content: WaSendMessageContent, options: WaSendMessageOptions, contextInfo: WaSendContextInfo | null) => Promise<WaMessagePublishResult>;
     readonly getIcdcHashLength?: () => number;
-    readonly mobileMessageIdFormat?: boolean;
+    /**
+     * Resolved per outgoing message (post-connect, after credentials load) so a
+     * registered mobile session reconnecting without an explicit
+     * `mobileTransport` option still emits the mobile message-id format.
+     */
+    readonly mobileMessageIdFormat?: () => boolean;
     readonly serverClock: ServerClock;
 }
 export declare class WaMessageDispatchCoordinator {

package/dist/client/coordinators/WaMessageDispatchCoordinator.js

@@ -26,7 +26,7 @@ class WaMessageDispatchCoordinator {
         this.privacyTokenDedup = new PromiseDedup_1.PromiseDedup();
         this.distributionDedup = new PromiseDedup_1.PromiseDedup();
         this.deps = options;
-        this.mobileMessageIdFormat = options.mobileMessageIdFormat ?? false;
+        this.mobileMessageIdFormat = options.mobileMessageIdFormat ?? (() => false);
         this.serverClock = options.serverClock;
     }
     async publishMessageNode(node, options = {}) {
@@ -68,17 +68,20 @@ class WaMessageDispatchCoordinator {
     }
     async publishSignalMessage(input, options = {}) {
         this.requireCurrentMeJid('publishSignalMessage');
-        const address = (0, jid_1.parseSignalAddressFromJid)(input.to);
+        const credentials = this.deps.getCurrentCredentials();
+        const sessionJid = (0, jid_1.canonicalizeOwnAccountJid)(input.to, credentials?.meJid, credentials?.meLid);
+        const address = (0, jid_1.parseSignalAddressFromJid)(sessionJid);
         if (address.server === constants_1.WA_DEFAULTS.GROUP_SERVER) {
             throw new Error('publishSignalMessage currently supports only direct chats; use sender-key flow for groups');
         }
         this.deps.logger.trace('wa client publish signal message', {
             to: input.to,
+            sessionJid,
             type: input.type
         });
         const [paddedPlaintext] = await Promise.all([
             (0, padding_1.writeRandomPadMax16)(input.plaintext),
-            this.deps.sessionResolver.ensureSession(address, input.to, input.expectedIdentity)
+            this.deps.sessionResolver.ensureSession(address, sessionJid, input.expectedIdentity)
         ]);
         const encrypted = await this.deps.signalProtocol.encryptMessage(address, paddedPlaintext, input.expectedIdentity);
         const messageType = input.type ?? 'text';
@@ -325,7 +328,8 @@ class WaMessageDispatchCoordinator {
         await this.deps.messageClient.sendReceipt(input);
     }
     async publishProtocolMessageToDevice(deviceJid, protocolMessage, options) {
-        const meJid = this.deps.getCurrentCredentials()?.meJid;
+        const credentials = this.deps.getCurrentCredentials();
+        const meJid = credentials?.meJid;
         const meParsed = meJid ? (0, jid_1.parseJidFull)(meJid) : undefined;
         const meUserJid = meParsed?.userJid;
         let senderIcdc = null;
@@ -657,7 +661,7 @@ class WaMessageDispatchCoordinator {
         const serverAddressingMode = result.ack.addressingMode;
         const hasPhashMismatch = !!serverPhash && serverPhash !== localPhash;
         const hasAddressingMismatch = !!serverAddressingMode && serverAddressingMode !== addressingMode;
-        const hasAddressingError = ackError === 421;
+        const hasAddressingError = ackError === constants_1.WA_NACK_REASONS.STALE_GROUP_ADDRESSING_MODE;
         if (!retryContext.retried &&
             (hasPhashMismatch || hasAddressingMismatch || hasAddressingError)) {
             this.deps.logger.warn('group direct publish acknowledged with mismatch metadata', {
@@ -832,7 +836,7 @@ class WaMessageDispatchCoordinator {
         const serverAddressingMode = result.ack.addressingMode;
         const hasPhashMismatch = !!serverPhash && serverPhash !== localPhash;
         const hasAddressingMismatch = !!serverAddressingMode && serverAddressingMode !== addressingMode;
-        const hasAddressingError = ackError === 421;
+        const hasAddressingError = ackError === constants_1.WA_NACK_REASONS.STALE_GROUP_ADDRESSING_MODE;
         if (!retryContext.retried &&
             (hasPhashMismatch || hasAddressingMismatch || hasAddressingError)) {
             this.deps.logger.warn('group message publish acknowledged with mismatch metadata', {
@@ -1194,7 +1198,7 @@ class WaMessageDispatchCoordinator {
             const meUserJid = (0, jid_1.toUserJid)(this.requireCurrentMeJid('sendMessage'));
             const timestampBytes = new Uint8Array(8);
             const dv = new DataView(timestampBytes.buffer, timestampBytes.byteOffset, timestampBytes.byteLength);
-            if (this.mobileMessageIdFormat) {
+            if (this.mobileMessageIdFormat()) {
                 dv.setBigUint64(0, BigInt(Date.now()), false);
                 const digest = (0, primitives_1.md5Bytes)([
                     timestampBytes,
@@ -1216,7 +1220,7 @@ class WaMessageDispatchCoordinator {
             this.deps.logger.warn('failed to generate message id, falling back to random', {
                 message: (0, primitives_2.toError)(error).message
             });
-            if (this.mobileMessageIdFormat) {
+            if (this.mobileMessageIdFormat()) {
                 const bytes = await (0, _crypto_1.randomBytesAsync)(16);
                 bytes[0] = 0xac;
                 return (0, bytes_1.bytesToHex)(bytes).toUpperCase();

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

@@ -40,7 +40,12 @@ export declare class WaPassiveTasksCoordinator {
         readonly signedPreKeyRotationIntervalMs?: number;
         readonly signedPreKeyServerErrorBackoffMs?: number;
         readonly runtime: WaPassiveTasksRuntime;
-        readonly mobilePrimary?: boolean;
+        /**
+         * Resolved when passive tasks run (post-connect, after credentials
+         * load) so a registered mobile-primary session reconnecting without an
+         * explicit `mobileTransport` option still bootstraps the primary path.
+         */
+        readonly mobilePrimary?: () => boolean;
         readonly appStateSync?: WaAppStateSyncClient;
     });
     startPassiveTasksAfterConnect(): void;

package/dist/client/coordinators/WaPassiveTasksCoordinator.js

@@ -19,7 +19,7 @@ class WaPassiveTasksCoordinator {
         this.signedPreKeyServerErrorBackoffMs =
             options.signedPreKeyServerErrorBackoffMs ?? constants_2.SIGNAL_SIGNED_PREKEY_SERVER_ERROR_BACKOFF_MS;
         this.runtime = options.runtime;
-        this.mobilePrimary = options.mobilePrimary ?? false;
+        this.mobilePrimary = options.mobilePrimary ?? (() => false);
         this.appStateSync = options.appStateSync;
         this.passiveTasksPromise = null;
     }
@@ -62,7 +62,7 @@ class WaPassiveTasksCoordinator {
             return;
         }
         this.runtime.syncAbProps();
-        if (this.mobilePrimary && this.appStateSync) {
+        if (this.mobilePrimary() && this.appStateSync) {
             await this.appStateSync.ensureInitialSyncKey().catch((error) => {
                 this.logger.warn('app-state initial key generation failed', {
                     message: (0, primitives_1.toError)(error).message
@@ -149,7 +149,7 @@ class WaPassiveTasksCoordinator {
         const response = await this.runtime.queryWithContext('prekeys.upload', uploadNode, constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS, {
             count: preKeys.length,
             lastPreKeyId
-        }, this.mobilePrimary ? { useSystemId: true } : undefined);
+        }, this.mobilePrimary() ? { useSystemId: true } : undefined);
         if (response.attrs.type === constants_1.WA_IQ_TYPES.RESULT) {
             // Mark uploaded key first so the serverHasPreKeys flag never commits ahead of local key progress.
             await this.preKeyStore.markKeyAsUploaded(lastPreKeyId);

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

@@ -21,6 +21,12 @@ export interface WaPresenceCoordinator {
 interface WaPresenceCoordinatorOptions {
     readonly sendNode: (node: BinaryNode) => Promise<void>;
     readonly getCurrentCredentials: () => WaAuthCredentials | null;
+    /**
+     * Resolves the receiver-mode `<tctoken>` node for a contact, echoed back
+     * on a user presence subscription to unlock the target's presence
+     * visibility. Returns `null` when no valid token is held.
+     */
+    readonly resolvePrivacyTokenNode: (jid: string) => Promise<BinaryNode | null>;
 }
 /** Builds a {@link WaPresenceCoordinator} from its node-send dependency. */
 export declare function createPresenceCoordinator(options: WaPresenceCoordinatorOptions): WaPresenceCoordinator;

package/dist/client/coordinators/WaPresenceCoordinator.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPresenceCoordinator = createPresenceCoordinator;
+const jid_1 = require("../../protocol/jid");
 const chatstate_1 = require("../../transport/node/builders/chatstate");
 const presence_1 = require("../../transport/node/builders/presence");
 /** Builds a {@link WaPresenceCoordinator} from its node-send dependency. */
 function createPresenceCoordinator(options) {
-    const { sendNode, getCurrentCredentials } = options;
+    const { sendNode, getCurrentCredentials, resolvePrivacyTokenNode } = options;
     return {
         send: async (type) => {
             const credentials = getCurrentCredentials();
@@ -15,7 +16,12 @@ function createPresenceCoordinator(options) {
             await sendNode((0, chatstate_1.buildChatstateNode)({ jid, ...opts }));
         },
         subscribe: async (jid, opts) => {
-            await sendNode((0, presence_1.buildPresenceSubscribeNode)({ jid, ...opts }));
+            const privacyTokenNode = (0, jid_1.isGroupJid)(jid) ? null : await resolvePrivacyTokenNode(jid);
+            await sendNode((0, presence_1.buildPresenceSubscribeNode)({
+                jid,
+                ...opts,
+                ...(privacyTokenNode ? { privacyTokenNode } : {})
+            }));
         }
     };
 }

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

@@ -79,12 +79,11 @@ export interface WaProfileCoordinator {
     readonly setStatus: (text: string) => Promise<void>;
     /**
      * Sets the account's pushName - the display name broadcast to other
-     * users in chats and group participant lists. WhatsApp Web applies the
-     * change via a `SettingPushName` app-state mutation (collection
-     * `critical_block`); the new value reaches peers as their next
-     * incoming-message envelope from this account carries the updated
-     * `notify` attr. Empty strings are accepted but reset the display name
-     * to the device fingerprint default.
+     * users in chats and group participant lists. Writes a `SettingPushName`
+     * app-state mutation to sync the account's other devices, persists the
+     * name locally, and re-broadcasts an available presence carrying it (the
+     * step that propagates the name on primary connections, where no phone
+     * re-broadcasts on this device's behalf). Empty strings clear the name.
      */
     readonly setPushName: (name: string) => Promise<void>;
     /** Batched usync fetch of picture id + status for many JIDs. */
@@ -144,6 +143,19 @@ interface WaProfileCoordinatorOptions {
      * mutations.
      */
     readonly mutations: WaAppStateMutationCoordinator;
+    /**
+     * Applies a pushName change locally: persists the display name and
+     * re-broadcasts an available presence carrying it. Expected to be
+     * idempotent (a no-op when the name already matches).
+     */
+    readonly applyOwnPushName: (name: string) => Promise<void>;
+    /**
+     * Resolves the receiver-mode `<tctoken>` node for a contact, echoed back on
+     * privacy-gated profile queries (picture get, about/status usync) to prove
+     * this account is a trusted contact. Returns `null` when no valid token is
+     * held for the JID.
+     */
+    readonly resolvePrivacyTokenNode: (jid: string) => Promise<BinaryNode | null>;
     readonly logger: Logger;
 }
 /** Builds a {@link WaProfileCoordinator} from its IQ/MEX/SID dependencies. */