zapo-js 1.9.0 → 1.11.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/auth/WaAuthClient.d.ts

@@ -146,6 +146,11 @@ export declare class WaAuthClient {
      * call this. The user then enters the returned code in WhatsApp on their
      * phone under *Linked Devices → Link with phone number instead*.
      *
+     * The server binds the code to the connection that requested it. If the
+     * socket drops and reconnects first, the client registers the same code on
+     * the new connection; if that fails, `auth_pairing_required` fires with
+     * `forceManual: true` and a new code must be requested.
+     *
      * @example
      * ```ts
      * // Start the handshake; do NOT await – connect() resolves only after pairing

package/dist/auth/WaAuthClient.js

@@ -307,6 +307,11 @@ class WaAuthClient {
      * call this. The user then enters the returned code in WhatsApp on their
      * phone under *Linked Devices → Link with phone number instead*.
      *
+     * The server binds the code to the connection that requested it. If the
+     * socket drops and reconnects first, the client registers the same code on
+     * the new connection; if that fails, `auth_pairing_required` fires with
+     * `forceManual: true` and a new code must be requested.
+     *
      * @example
      * ```ts
      * // Start the handshake; do NOT await – connect() resolves only after pairing

package/dist/auth/pairing/WaPairingFlow.d.ts

@@ -31,6 +31,7 @@ interface WaPairingFlowOptions {
 export declare class WaPairingFlow {
     private readonly opts;
     private pairingSession;
+    private rearmGeneration;
     private pairSuccessInFlight;
     constructor(options: WaPairingFlowOptions);
     hasPairingSession(): boolean;
@@ -48,6 +49,16 @@ export declare class WaPairingFlow {
     /** Mirrors the `not-authorized` IQ error WhatsApp Web returns on a failed pair-success. */
     private sendPairSuccessValidationError;
     private handlePrimaryHello;
+    private sendCompanionHello;
+    /**
+     * The server delivers `primary_hello` only to the connection that sent the
+     * `companion_hello`, so a code requested on a dropped connection is dead.
+     * Registers the same code again, without a push, like WA Web's code refresh.
+     * The ADV secret is not rotated: the QR just emitted for this connection carries it.
+     * Only the latest pair-device may settle the session, since an older attempt can
+     * outlive its dropped connection until the IQ times out.
+     */
+    private rearmPairingCode;
     private rotateAdvSecret;
     private requireCredentials;
 }

package/dist/auth/pairing/WaPairingFlow.js

@@ -19,6 +19,7 @@ const PAIR_SUCCESS_DEVICE_IDENTITY_MIN_BYTES = 1;
 const PAIR_SUCCESS_DEVICE_IDENTITY_MAX_BYTES = 500;
 class WaPairingFlow {
     constructor(options) {
+        this.rearmGeneration = 0;
         this.pairSuccessInFlight = false;
         this.opts = options;
         this.pairingSession = null;
@@ -38,49 +39,17 @@ class WaPairingFlow {
         const normalizedCustomCode = customCode !== undefined ? (0, pairing_code_crypto_1.normalizeCustomPairingCode)(customCode) : undefined;
         const credentials = this.requireCredentials();
         const phoneJid = (0, jid_1.parsePhoneJid)(phoneNumber);
-        const createdAtSeconds = Math.floor(Date.now() / 1000);
-        const [companionHello, refreshedCredentials] = await Promise.all([
-            (0, pairing_code_crypto_1.createCompanionHello)({ customCode: normalizedCustomCode }),
+        const [session] = await Promise.all([
+            this.sendCompanionHello(phoneJid, shouldShowPushNotification, normalizedCustomCode),
             this.rotateAdvSecret(credentials)
         ]);
-        const browserDisplayName = (0, browser_1.getWaBrowserDisplayName)(this.opts.device.browser);
-        const response = await this.opts.socket.query((0, pairing_1.buildCompanionHelloRequestNode)({
-            phoneJid,
-            shouldShowPushNotification,
-            wrappedCompanionEphemeralPub: companionHello.wrappedCompanionEphemeralPub,
-            companionServerAuthKeyPub: refreshedCredentials.noiseKeyPair.pubKey,
-            companionPlatformId: this.opts.device.platform,
-            companionPlatformDisplay: `${browserDisplayName} (${this.opts.device.osDisplayName})`
-        }), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
-        this.opts.logger.debug('pairing code request response received', {
-            responseTag: response.tag,
-            responseType: response.attrs.type
-        });
-        (0, query_1.assertIqResult)(response, 'companion hello');
-        const linkCodeNode = (0, helpers_1.findNodeChild)(response, constants_1.WA_NODE_TAGS.LINK_CODE_COMPANION_REG);
-        if (!linkCodeNode) {
-            throw new Error('companion hello response missing link_code_companion_reg');
-        }
-        const refNode = (0, helpers_1.findNodeChild)(linkCodeNode, constants_1.WA_NODE_TAGS.LINK_CODE_PAIRING_REF);
-        if (!refNode) {
-            throw new Error('companion hello response missing link_code_pairing_ref');
-        }
-        const ref = (0, helpers_1.decodeNodeContentUtf8OrBytes)(refNode.content, 'link_code_pairing_ref');
-        this.pairingSession = {
-            pairingCode: companionHello.pairingCode,
-            phoneJid,
-            ref,
-            createdAtSeconds,
-            companionEphemeralKeyPair: companionHello.companionEphemeralKeyPair,
-            attempts: 0,
-            finished: false
-        };
-        this.opts.callbacks.emitPairingCode(companionHello.pairingCode);
+        this.pairingSession = session;
+        this.opts.callbacks.emitPairingCode(session.pairingCode);
         this.opts.logger.debug('pairing code emitted', {
             phoneJid,
-            createdAtSeconds: this.pairingSession.createdAtSeconds
+            createdAtSeconds: session.createdAtSeconds
         });
-        return companionHello.pairingCode;
+        return session.pairingCode;
     }
     async fetchPairingCountryCodeIso() {
         this.opts.logger.trace('fetching pairing country code ISO');
@@ -170,6 +139,15 @@ class WaPairingFlow {
         await this.opts.socket.sendNode((0, global_1.buildIqResultNode)(iqNode));
         this.opts.qrFlow.setRefs(refs);
         this.opts.logger.debug('pair-device refs updated', { refsCount: refs.length });
+        // The server sends pair-device once per connection: a pending code belongs to an older one.
+        if (this.pairingSession) {
+            const generation = ++this.rearmGeneration;
+            void this.rearmPairingCode(this.pairingSession, generation).catch((error) => {
+                this.opts.logger.warn('pairing code re-registration failed unexpectedly', {
+                    message: (0, primitives_1.toError)(error).message
+                });
+            });
+        }
     }
     async handlePairSuccess(iqNode, pairSuccessNode) {
         if (this.pairSuccessInFlight) {
@@ -231,7 +209,13 @@ class WaPairingFlow {
             await this.sendPairSuccessValidationError(iqNode);
             throw new Error('pair-success account signature validation failed');
         }
-        const { signedIdentity, keyIndex, responseIdentityBytes } = built;
+        const { signedIdentity, keyIndex, responseIdentityBytes, advDeviceIdentity } = built;
+        this.opts.logger.debug('pair-success adv identity', {
+            envelopeAccountType: wrappedIdentity.accountType ?? null,
+            accountType: advDeviceIdentity.accountType ?? null,
+            deviceType: advDeviceIdentity.deviceType ?? null,
+            keyIndex: advDeviceIdentity.keyIndex ?? null
+        });
         const nextCredentials = {
             ...credentials,
             signedIdentity,
@@ -301,7 +285,8 @@ class WaPairingFlow {
         return {
             signedIdentity,
             keyIndex: advDeviceIdentity.keyIndex ?? 0,
-            responseIdentityBytes
+            responseIdentityBytes,
+            advDeviceIdentity
         };
     }
     /** Mirrors the `not-authorized` IQ error WhatsApp Web returns on a failed pair-success. */
@@ -377,6 +362,78 @@ class WaPairingFlow {
         pairingSession.finished = true;
         this.opts.logger.debug('primary_hello completed with companion_finish success');
     }
+    async sendCompanionHello(phoneJid, shouldShowPushNotification, customCode) {
+        const credentials = this.requireCredentials();
+        const createdAtSeconds = Math.floor(Date.now() / 1000);
+        const companionHello = await (0, pairing_code_crypto_1.createCompanionHello)({ customCode });
+        const browserDisplayName = (0, browser_1.getWaBrowserDisplayName)(this.opts.device.browser);
+        const response = await this.opts.socket.query((0, pairing_1.buildCompanionHelloRequestNode)({
+            phoneJid,
+            shouldShowPushNotification,
+            wrappedCompanionEphemeralPub: companionHello.wrappedCompanionEphemeralPub,
+            companionServerAuthKeyPub: credentials.noiseKeyPair.pubKey,
+            companionPlatformId: this.opts.device.platform,
+            companionPlatformDisplay: `${browserDisplayName} (${this.opts.device.osDisplayName})`
+        }), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
+        this.opts.logger.debug('pairing code request response received', {
+            responseTag: response.tag,
+            responseType: response.attrs.type
+        });
+        (0, query_1.assertIqResult)(response, 'companion hello');
+        const linkCodeNode = (0, helpers_1.findNodeChild)(response, constants_1.WA_NODE_TAGS.LINK_CODE_COMPANION_REG);
+        if (!linkCodeNode) {
+            throw new Error('companion hello response missing link_code_companion_reg');
+        }
+        const refNode = (0, helpers_1.findNodeChild)(linkCodeNode, constants_1.WA_NODE_TAGS.LINK_CODE_PAIRING_REF);
+        if (!refNode) {
+            throw new Error('companion hello response missing link_code_pairing_ref');
+        }
+        return {
+            pairingCode: companionHello.pairingCode,
+            phoneJid,
+            ref: (0, helpers_1.decodeNodeContentUtf8OrBytes)(refNode.content, 'link_code_pairing_ref'),
+            createdAtSeconds,
+            companionEphemeralKeyPair: companionHello.companionEphemeralKeyPair,
+            attempts: 0,
+            finished: false
+        };
+    }
+    /**
+     * The server delivers `primary_hello` only to the connection that sent the
+     * `companion_hello`, so a code requested on a dropped connection is dead.
+     * Registers the same code again, without a push, like WA Web's code refresh.
+     * The ADV secret is not rotated: the QR just emitted for this connection carries it.
+     * Only the latest pair-device may settle the session, since an older attempt can
+     * outlive its dropped connection until the IQ times out.
+     */
+    async rearmPairingCode(previous, generation) {
+        const isCurrent = () => this.pairingSession === previous && this.rearmGeneration === generation;
+        try {
+            const session = await this.sendCompanionHello(previous.phoneJid, false, previous.pairingCode);
+            if (!isCurrent()) {
+                this.opts.logger.debug('pairing code re-registration superseded');
+                return;
+            }
+            this.pairingSession = session;
+            this.opts.logger.info('pairing code re-registered on the new connection', {
+                phoneJid: session.phoneJid
+            });
+        }
+        catch (error) {
+            const message = (0, primitives_1.toError)(error).message;
+            if (!isCurrent()) {
+                this.opts.logger.debug('superseded pairing code re-registration failed', {
+                    message
+                });
+                return;
+            }
+            this.pairingSession = null;
+            this.opts.logger.warn('failed to re-register pairing code on the new connection', {
+                message
+            });
+            this.opts.callbacks.emitPairingRefresh(true);
+        }
+    }
     async rotateAdvSecret(credentials) {
         const nextCredentials = {
             ...credentials,

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

@@ -275,6 +275,8 @@ class WaClientImpl extends node_events_1.EventEmitter {
                         mediaTransfer: this.mediaTransfer,
                         chatMetadataStore: this.stores.chatMetadata,
                         writeBehind: this.writeBehind,
+                        chunkId: event.key.id,
+                        sink: this.options.history?.sink,
                         emitEvent: this.emit.bind(this),
                         onPrivacyTokens: (conversations) => this.deps.trustedContactToken.hydrateFromHistorySync(conversations),
                         onNctSalt: (salt) => this.deps.trustedContactToken.hydrateNctSaltFromHistorySync(salt),
@@ -458,6 +460,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 +475,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/WaClientFactory.js

@@ -211,7 +211,7 @@ function buildWaClientDependencies(input) {
     let connectionManager = null;
     let passiveTasks = null;
     let mediaConnCacheFallback = null;
-    let scheduleReconnectAfterPairing = () => undefined;
+    let awaitServerRestartAfterPairing = () => undefined;
     const serverClock = (0, clock_1.createServerClock)(() => connectionManager?.getClockSkewMs() ?? null);
     const nodeTransport = new WaNodeTransport_1.WaNodeTransport(logger);
     const nodeOrchestrator = new WaNodeOrchestrator_1.WaNodeOrchestrator({
@@ -338,7 +338,7 @@ function buildWaClientDependencies(input) {
         deviceOsDisplayName: options.deviceOsDisplayName,
         deviceOsVersion: options.deviceOsVersion,
         devicePlatform: options.devicePlatform,
-        requireFullSync: options.requireFullSync,
+        requireFullSync: options.history?.requireFullSync ?? options.requireFullSync,
         version: options.version,
         dangerous: options.dangerous,
         mobileTransport: options.mobileTransport
@@ -358,7 +358,7 @@ function buildWaClientDependencies(input) {
             onPairingRefresh: (forceManual) => runtime.emitEvent('auth_pairing_required', { forceManual }),
             onPaired: (credentials) => {
                 runtime.emitEvent('auth_paired', { credentials });
-                scheduleReconnectAfterPairing();
+                awaitServerRestartAfterPairing();
             },
             onError: (error) => runtime.handleError(error),
             onPasskeyRequired: (hasSigner) => runtime.emitEvent('auth_passkey_required', { hasSigner }),
@@ -671,7 +671,7 @@ function buildWaClientDependencies(input) {
     if (mediaConnCacheFallback !== null) {
         connectionManager.setMediaConnCache(mediaConnCacheFallback);
     }
-    scheduleReconnectAfterPairing = () => connectionManager?.scheduleReconnectAfterPairing();
+    awaitServerRestartAfterPairing = () => connectionManager?.awaitServerRestartAfterPairing();
     const disconnectWithClientSideEffects = async (reason, isLogout, code) => {
         abPropsCoordinator.reset();
         offlineResume.reset();
@@ -712,7 +712,8 @@ function buildWaClientDependencies(input) {
         },
         disconnect: disconnectWithClientSideEffects,
         clearStoredCredentials: clearStoredCredentialsWithClientSideEffects,
-        connect: connectWithClientSideEffects
+        connect: connectWithClientSideEffects,
+        handlePairingRestart: () => connectionManager?.handleServerRestartRequest() ?? false
     });
     const incomingMessageAckOptions = {
         logger,

package/dist/client/connection/WaConnectionManager.d.ts

@@ -33,14 +33,24 @@ export declare class WaConnectionManager {
     private mediaConnCache;
     private connectPromise;
     private pairingReconnectPromise;
-    private pairingReconnectTimeout;
+    private pairRestartTimer;
     private frameHandler;
     private pendingComms;
     private lifecycleGeneration;
     private lifecycleQueue;
     constructor(options: WaConnectionManagerOptions);
     connect(frameHandler: (frame: Uint8Array) => Promise<void>): Promise<void>;
-    scheduleReconnectAfterPairing(): void;
+    /**
+     * Starts the post-pairing restart window: the server ends the unregistered connection
+     * itself (`stream:error` 515, as WA Web waits for), so the socket stays open until that
+     * signal, a server close, or the fallback timer, whichever comes first.
+     */
+    awaitServerRestartAfterPairing(): void;
+    /**
+     * Claims a `stream:error` 515 for the post-pairing restart. Returns `true` while the
+     * window is open or its restart is running, so the generic force-login path must skip it.
+     */
+    handleServerRestartRequest(): boolean;
     disconnect(): Promise<void>;
     clearStoredCredentials(): Promise<void>;
     isConnected(): boolean;
@@ -51,6 +61,8 @@ export declare class WaConnectionManager {
     updateClockSkewFromSuccess(serverUnixSeconds: number): void;
     setClockSkewMs(clockSkewMs: number, source: string): void;
     private connectInternal;
+    private startPairRestart;
+    private clearPairRestartTimer;
     private reconnectAsRegisteredAfterPairing;
     private reconnectAsRegisteredAfterPairingInternal;
     private disconnectInternal;

package/dist/client/connection/WaConnectionManager.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaConnectionManager = void 0;
+const constants_1 = require("../../protocol/constants");
 const WaComms_1 = require("../../transport/WaComms");
 const primitives_1 = require("../../util/primitives");
 class WaConnectionManager {
@@ -19,7 +20,7 @@ class WaConnectionManager {
         this.mediaConnCache = null;
         this.connectPromise = null;
         this.pairingReconnectPromise = null;
-        this.pairingReconnectTimeout = null;
+        this.pairRestartTimer = null;
         this.frameHandler = null;
         this.pendingComms = null;
         this.lifecycleGeneration = 0;
@@ -43,26 +44,37 @@ class WaConnectionManager {
         this.connectPromise = promise;
         return this.connectPromise;
     }
-    scheduleReconnectAfterPairing() {
-        this.logger.debug('wa client scheduling reconnect after pairing');
-        if (this.pairingReconnectTimeout) {
-            clearTimeout(this.pairingReconnectTimeout);
+    /**
+     * Starts the post-pairing restart window: the server ends the unregistered connection
+     * itself (`stream:error` 515, as WA Web waits for), so the socket stays open until that
+     * signal, a server close, or the fallback timer, whichever comes first.
+     */
+    awaitServerRestartAfterPairing() {
+        const comms = this.comms;
+        if (!comms) {
+            this.logger.trace('pairing restart wait skipped: no active comms');
+            return;
         }
-        this.pairingReconnectTimeout = setTimeout(() => {
-            this.pairingReconnectTimeout = null;
-            void this.reconnectAsRegisteredAfterPairing().catch((error) => {
-                if (this.isLifecycleSupersededError(error)) {
-                    this.logger.trace('pairing reconnect canceled by newer lifecycle');
-                    return;
-                }
-                this.logger.warn('failed to reconnect after pairing', {
-                    meJid: this.authClient.getCurrentCredentials()?.meJid,
-                    message: (0, primitives_1.toError)(error).message
-                });
-            });
-        }, 0);
+        this.clearPairRestartTimer();
+        this.logger.debug('wa client waiting for server restart after pairing', {
+            fallbackMs: constants_1.WA_DEFAULTS.PAIRING_RESTART_WAIT_MS
+        });
+        this.pairRestartTimer = setTimeout(() => this.startPairRestart('fallback_timeout'), constants_1.WA_DEFAULTS.PAIRING_RESTART_WAIT_MS);
+        comms.holdForServerRestart(() => this.startPairRestart('socket_closed'));
+    }
+    /**
+     * Claims a `stream:error` 515 for the post-pairing restart. Returns `true` while the
+     * window is open or its restart is running, so the generic force-login path must skip it.
+     */
+    handleServerRestartRequest() {
+        if (this.pairRestartTimer) {
+            this.startPairRestart('stream_error_515');
+            return true;
+        }
+        return this.pairingReconnectPromise !== null;
     }
     async disconnect() {
+        this.clearPairRestartTimer();
         const lifecycleGeneration = this.nextLifecycleGeneration();
         this.invalidatePendingComms('failed to stop pending comms during disconnect');
         await this.runLifecycleOperation(async () => {
@@ -140,6 +152,30 @@ class WaConnectionManager {
         this.assertLifecycleCurrent(lifecycleGeneration, 'connect');
         this.logger.info('wa client connected');
     }
+    startPairRestart(trigger) {
+        if (!this.pairRestartTimer) {
+            return;
+        }
+        this.clearPairRestartTimer();
+        this.logger.debug('wa client restarting after pairing', { trigger });
+        void this.reconnectAsRegisteredAfterPairing().catch((error) => {
+            if (this.isLifecycleSupersededError(error)) {
+                this.logger.trace('pairing reconnect canceled by newer lifecycle');
+                return;
+            }
+            this.logger.warn('failed to reconnect after pairing', {
+                meJid: this.authClient.getCurrentCredentials()?.meJid,
+                message: (0, primitives_1.toError)(error).message
+            });
+        });
+    }
+    clearPairRestartTimer() {
+        if (!this.pairRestartTimer) {
+            return;
+        }
+        clearTimeout(this.pairRestartTimer);
+        this.pairRestartTimer = null;
+    }
     async reconnectAsRegisteredAfterPairing() {
         if (this.pairingReconnectPromise) {
             this.logger.trace('pairing reconnect already in-flight');
@@ -188,10 +224,7 @@ class WaConnectionManager {
             return;
         }
         this.logger.debug('wa client disconnect start');
-        if (this.pairingReconnectTimeout) {
-            clearTimeout(this.pairingReconnectTimeout);
-            this.pairingReconnectTimeout = null;
-        }
+        this.clearPairRestartTimer();
         this.keepAlive.stop();
         this.nodeOrchestrator.clearPending(new Error('client disconnected'));
         this.clockSkewMs = null;

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

@@ -110,6 +110,13 @@ export interface WaRequestHistorySyncInput {
      */
     readonly count?: number;
 }
+/** Options for {@link WaMessageCoordinator.syncSignalSession}. */
+export interface WaSyncSignalSessionOptions {
+    /** Drops the session, keeping the identity, and fetches a fresh one. */
+    readonly force?: boolean;
+    /** The identity changed: drops the session and fetches with `reason="identity"`. */
+    readonly reasonIdentity?: boolean;
+}
 export interface WaReachoutTimelock {
     readonly isActive: boolean;
     readonly enforcementType: string | null;
@@ -239,11 +246,16 @@ export declare class WaMessageCoordinator {
      */
     getNewChatMessageCapping(type?: WaMessageCappingType): Promise<WaMessageCappingInfo>;
     /**
-     * Force-refreshes the Signal session(s) for `jid`. Set `reasonIdentity` to
-     * `true` when the trigger was an identity change – this also queues a
-     * trusted-contact-token reissue.
+     * Syncs the Signal session of the device `jid` resolves to (a user JID is
+     * device 0). With no options it only ensures a session exists. `force`
+     * rebuilds it, keeping the identity. `reasonIdentity` rebuilds it as an
+     * identity change and reissues the trusted-contact token; it wins over
+     * `force`. Throws for group JIDs and when the key-bundle fetch fails, in
+     * which case the old session is already gone.
      */
-    syncSignalSession(jid: string, reasonIdentity?: boolean): Promise<void>;
+    syncSignalSession(jid: string, options?: WaSyncSignalSessionOptions): Promise<void>;
+    /** @deprecated Pass `{ reasonIdentity: true }` instead. */
+    syncSignalSession(jid: string, reasonIdentity: boolean): Promise<void>;
     /**
      * Sends a message (any {@link WaSendMessageContent} kind – text, media,
      * poll, reaction, edit, revoke, etc.) to `to` and returns the publish
@@ -384,10 +396,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/WaMessageCoordinator.js

@@ -292,14 +292,10 @@ class WaMessageCoordinator {
         });
         return parseMessageCappingMexResponse(data);
     }
-    /**
-     * Force-refreshes the Signal session(s) for `jid`. Set `reasonIdentity` to
-     * `true` when the trigger was an identity change – this also queues a
-     * trusted-contact-token reissue.
-     */
-    async syncSignalSession(jid, reasonIdentity = false) {
-        await this.messageDispatch.syncSignalSession(jid, reasonIdentity);
-        if (reasonIdentity) {
+    async syncSignalSession(jid, options = {}) {
+        const normalized = typeof options === 'boolean' ? { reasonIdentity: options } : options;
+        await this.messageDispatch.syncSignalSession(jid, normalized);
+        if (normalized.reasonIdentity) {
             this.trustedContactToken.reissueOnIdentityChange(jid).catch((err) => this.logger.warn('tc token reissue on identity change failed', {
                 jid,
                 message: (0, primitives_1.toError)(err).message

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

@@ -1,5 +1,6 @@
 import type { WaAppStateSyncKey } from '../../appstate/types';
 import type { WaAuthCredentials } from '../../auth/types';
+import type { WaSyncSignalSessionOptions } from '../coordinators/WaMessageCoordinator';
 import type { DeviceFanoutResolver } from '../messaging/fanout';
 import type { GroupMetadataCache } from '../messaging/group-metadata';
 import type { AppStateSyncKeyProtocol } from '../messaging/key-protocol';
@@ -7,6 +8,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 +98,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;
@@ -145,7 +157,7 @@ export declare class WaMessageDispatchCoordinator {
      * LID destination.
      */
     private resolvePeerRecipientPn;
-    syncSignalSession(jid: string, reasonIdentity?: boolean): Promise<void>;
+    syncSignalSession(jid: string, { force, reasonIdentity }?: WaSyncSignalSessionOptions): Promise<void>;
     sendReceipt(input: WaSendReceiptInput): Promise<void>;
     publishProtocolMessageToDevice(deviceJid: string, protocolMessage: Proto.Message.IProtocolMessage, options?: {
         readonly id?: string;