zapo-js 1.3.0 → 1.5.0

package/dist/client/messaging/companion-host.d.ts

@@ -0,0 +1,43 @@
+import { type Proto } from '../../proto';
+/** A PN→LID mapping carried inside a history sync (one per chat peer with a LID). */
+export interface PhoneNumberToLidMapping {
+    readonly pnJid: string;
+    readonly lidJid: string;
+}
+export interface HistorySyncBootstrapInput {
+    /**
+     * Chat-peer PN→LID pairs (the primary's own account excluded, only peers
+     * resolving to a LID). A fresh account with no chats yields an empty list.
+     */
+    readonly phoneNumberToLidMappings?: readonly PhoneNumberToLidMapping[];
+    readonly conversations?: readonly Proto.IConversation[];
+    readonly pushnames?: readonly Proto.IPushname[];
+    /** The companion pairing session id, echoed so the companion can bind it. */
+    readonly companionMetaNonce?: string;
+}
+/**
+ * Serializes a `HistorySync` and zlib-deflates it. The phone uses DEFLATE
+ * level 1; any zlib-framed level inflates identically, so it is only a
+ * size/speed tradeoff.
+ */
+export declare function encodeHistorySync(content: Proto.IHistorySync): Promise<Uint8Array>;
+/**
+ * Wraps a deflated `HistorySync` inline in a `HISTORY_SYNC_NOTIFICATION` protocol
+ * message. Only small syncs are inlined; larger ones ride an external
+ * `md-msg-hist` MMS blob referenced by the same notification.
+ */
+export declare function buildInlineHistorySyncNotification(syncType: Proto.Message.HistorySyncType, deflatedPayload: Uint8Array, options?: {
+    readonly chunkOrder?: number;
+    readonly progress?: number;
+}): Proto.Message.IProtocolMessage;
+/**
+ * Builds the `INITIAL_BOOTSTRAP` `HISTORY_SYNC_NOTIFICATION` a mobile-primary
+ * pushes to a freshly-linked companion: a deflated `HistorySync` wrapped in a
+ * protocol message for delivery as an encrypted peer message. Note
+ * `HistorySync.syncType` and `HistorySyncNotification.syncType` are distinct
+ * enum types with shared values, so each field uses its own.
+ */
+export declare function buildHistorySyncBootstrapMessage(input?: HistorySyncBootstrapInput): Promise<{
+    readonly message: Proto.Message.IProtocolMessage;
+    readonly payloadBytes: number;
+}>;

package/dist/client/messaging/companion-host.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeHistorySync = encodeHistorySync;
+exports.buildInlineHistorySyncNotification = buildInlineHistorySyncNotification;
+exports.buildHistorySyncBootstrapMessage = buildHistorySyncBootstrapMessage;
+const node_util_1 = require("node:util");
+const node_zlib_1 = require("node:zlib");
+const _proto_1 = require("../../proto");
+const deflateAsync = (0, node_util_1.promisify)(node_zlib_1.deflate);
+/**
+ * Serializes a `HistorySync` and zlib-deflates it. The phone uses DEFLATE
+ * level 1; any zlib-framed level inflates identically, so it is only a
+ * size/speed tradeoff.
+ */
+async function encodeHistorySync(content) {
+    const serialized = _proto_1.proto.HistorySync.encode(content).finish();
+    const compressed = await deflateAsync(serialized, { level: 1 });
+    return new Uint8Array(compressed);
+}
+/**
+ * Wraps a deflated `HistorySync` inline in a `HISTORY_SYNC_NOTIFICATION` protocol
+ * message. Only small syncs are inlined; larger ones ride an external
+ * `md-msg-hist` MMS blob referenced by the same notification.
+ */
+function buildInlineHistorySyncNotification(syncType, deflatedPayload, options = {}) {
+    return {
+        type: _proto_1.proto.Message.ProtocolMessage.Type.HISTORY_SYNC_NOTIFICATION,
+        historySyncNotification: {
+            syncType,
+            chunkOrder: options.chunkOrder ?? 0,
+            progress: options.progress ?? 100,
+            initialHistBootstrapInlinePayload: deflatedPayload
+        }
+    };
+}
+/**
+ * Builds the `INITIAL_BOOTSTRAP` `HISTORY_SYNC_NOTIFICATION` a mobile-primary
+ * pushes to a freshly-linked companion: a deflated `HistorySync` wrapped in a
+ * protocol message for delivery as an encrypted peer message. Note
+ * `HistorySync.syncType` and `HistorySyncNotification.syncType` are distinct
+ * enum types with shared values, so each field uses its own.
+ */
+async function buildHistorySyncBootstrapMessage(input = {}) {
+    const historySync = {
+        syncType: _proto_1.proto.HistorySync.HistorySyncType.INITIAL_BOOTSTRAP,
+        chunkOrder: 0,
+        progress: 100,
+        conversations: input.conversations ? [...input.conversations] : [],
+        pushnames: input.pushnames ? [...input.pushnames] : [],
+        phoneNumberToLidMappings: (input.phoneNumberToLidMappings ?? []).map((mapping) => ({
+            pnJid: mapping.pnJid,
+            lidJid: mapping.lidJid
+        })),
+        ...(input.companionMetaNonce !== undefined
+            ? { companionMetaNonce: input.companionMetaNonce }
+            : {})
+    };
+    const payload = await encodeHistorySync(historySync);
+    const message = buildInlineHistorySyncNotification(_proto_1.proto.Message.HistorySyncType.INITIAL_BOOTSTRAP, payload);
+    return { message, payloadBytes: payload.byteLength };
+}

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

@@ -4,6 +4,15 @@ exports.createAppStateSyncKeyProtocol = createAppStateSyncKeyProtocol;
 const _proto_1 = require("../../proto");
 const jid_1 = require("../../protocol/jid");
 const bytes_1 = require("../../util/bytes");
+/**
+ * Valid app-state sync key ids are exactly 6 bytes: a 2-byte device id followed
+ * by a 4-byte big-endian epoch (matching the phone primary's `crypto_info`
+ * (device_id, epoch) schema and WhatsApp Web's `handleAppStateSyncKeyShare`,
+ * which fatally rejects any share whose keyId byte length is not 6). A primary
+ * must never emit a malformed key, so legacy/short key ids are dropped from
+ * outgoing shares rather than poisoning the peer's syncd engine.
+ */
+const APP_STATE_SYNC_KEY_ID_LENGTH = 6;
 function createAppStateSyncKeyProtocol(options) {
     const { publishProtocolMessageToDevice, fanoutResolver, getCurrentCredentials, logger } = options;
     const requireCurrentIdentity = (context) => {
@@ -67,7 +76,12 @@ function createAppStateSyncKeyProtocol(options) {
         const seenKeyIds = new Set();
         const keyShareEntries = [];
         let sharedKeyCount = 0;
+        const droppedKeyIds = [];
         for (const key of keys) {
+            if (key.keyId.byteLength !== APP_STATE_SYNC_KEY_ID_LENGTH) {
+                droppedKeyIds.push((0, bytes_1.bytesToHex)(key.keyId));
+                continue;
+            }
             const keyHex = (0, bytes_1.bytesToHex)(key.keyId);
             if (seenKeyIds.has(keyHex)) {
                 continue;
@@ -84,7 +98,10 @@ function createAppStateSyncKeyProtocol(options) {
             });
         }
         for (const keyId of missingKeyIds) {
-            if (keyId.byteLength === 0) {
+            if (keyId.byteLength !== APP_STATE_SYNC_KEY_ID_LENGTH) {
+                if (keyId.byteLength > 0) {
+                    droppedKeyIds.push((0, bytes_1.bytesToHex)(keyId));
+                }
                 continue;
             }
             const keyHex = (0, bytes_1.bytesToHex)(keyId);
@@ -96,6 +113,13 @@ function createAppStateSyncKeyProtocol(options) {
                 keyId: { keyId }
             });
         }
+        if (droppedKeyIds.length > 0) {
+            logger.warn('app-state refusing to share malformed sync keys: keyId byte length must be 6', {
+                droppedCount: droppedKeyIds.length,
+                totalExpected: keys.length + missingKeyIds.length,
+                sample: droppedKeyIds.slice(0, 5)
+            });
+        }
         const protocolMessage = {
             type: _proto_1.proto.Message.ProtocolMessage.Type.APP_STATE_SYNC_KEY_SHARE,
             appStateSyncKeyShare: {

package/dist/client/persistence/companion-host.d.ts

@@ -0,0 +1,36 @@
+/** A companion device this primary has linked. */
+export interface CompanionRecord {
+    readonly deviceJid: string;
+    readonly keyIndex: number;
+    readonly companionIdentityPublicKey: Uint8Array;
+    readonly addedAtSeconds: number;
+}
+/**
+ * The primary's ADV epoch state. `rawId` is the account's stable ADV identity
+ * id; `currentKeyIndex` is the last-issued companion key index (companions get
+ * `currentKeyIndex + 1`). This MUST persist across restarts, otherwise reissuing
+ * an already-used key index breaks previously linked devices.
+ */
+export interface CompanionHostEpochState {
+    readonly rawId: number;
+    readonly currentKeyIndex: number;
+    readonly companions: readonly CompanionRecord[];
+}
+/**
+ * Persistence hook for {@link CompanionHostEpochState}. Supply one via plugin
+ * options to survive restarts; without it the epoch is in-memory only (fine for
+ * a single-session smoke test, unsafe for production relinking).
+ */
+export interface CompanionHostPersistence {
+    readonly load: () => Promise<CompanionHostEpochState | null> | CompanionHostEpochState | null;
+    readonly save: (state: CompanionHostEpochState) => Promise<void> | void;
+}
+/**
+ * File-backed {@link CompanionHostPersistence}: stores the ADV epoch as JSON at
+ * `filePath` (the companion identity keys are base64-encoded). Zero native
+ * dependencies - the state is tiny (the epoch header plus the linked-companion
+ * list). For a database-backed store, implement the two-method
+ * `CompanionHostPersistence` contract directly against your DB; there is no need
+ * for a dedicated core store domain.
+ */
+export declare function createFileCompanionHostPersistence(filePath: string): CompanionHostPersistence;

package/dist/client/persistence/companion-host.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileCompanionHostPersistence = createFileCompanionHostPersistence;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const bytes_1 = require("../../util/bytes");
+/**
+ * File-backed {@link CompanionHostPersistence}: stores the ADV epoch as JSON at
+ * `filePath` (the companion identity keys are base64-encoded). Zero native
+ * dependencies - the state is tiny (the epoch header plus the linked-companion
+ * list). For a database-backed store, implement the two-method
+ * `CompanionHostPersistence` contract directly against your DB; there is no need
+ * for a dedicated core store domain.
+ */
+function createFileCompanionHostPersistence(filePath) {
+    return {
+        async load() {
+            let raw;
+            try {
+                raw = await (0, promises_1.readFile)(filePath, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return null;
+                }
+                throw error;
+            }
+            const parsed = JSON.parse(raw);
+            return {
+                rawId: parsed.rawId,
+                currentKeyIndex: parsed.currentKeyIndex,
+                companions: parsed.companions.map((companion) => ({
+                    deviceJid: companion.deviceJid,
+                    keyIndex: companion.keyIndex,
+                    companionIdentityPublicKey: (0, bytes_1.base64ToBytes)(companion.companionIdentityPublicKey),
+                    addedAtSeconds: companion.addedAtSeconds
+                }))
+            };
+        },
+        async save(state) {
+            const serialized = {
+                rawId: state.rawId,
+                currentKeyIndex: state.currentKeyIndex,
+                companions: state.companions.map((companion) => ({
+                    deviceJid: companion.deviceJid,
+                    keyIndex: companion.keyIndex,
+                    companionIdentityPublicKey: (0, bytes_1.bytesToBase64)(companion.companionIdentityPublicKey),
+                    addedAtSeconds: companion.addedAtSeconds
+                }))
+            };
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(filePath), { recursive: true });
+            const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+            await (0, promises_1.writeFile)(tempPath, JSON.stringify(serialized), 'utf8');
+            await (0, promises_1.rename)(tempPath, filePath);
+        }
+    };
+}

package/dist/client/plugins/install.d.ts

@@ -13,6 +13,7 @@ export interface WaClientPluginInstallInput {
 }
 /**
  * Installs {@link WaClientOptions.plugins} on `client`. Returns a dispose
- * function invoked by {@link WaClient.disconnect}.
+ * function invoked by {@link WaClient.disconnect}. Safe to call again after a
+ * dispose to reinstall the same plugins on reconnect.
  */
 export declare function installWaClientPlugins(client: WaClient, input: WaClientPluginInstallInput, plugins: readonly WaClientPluginDefinition[]): () => Promise<void>;

package/dist/client/plugins/install.js

@@ -3,11 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.installWaClientPlugins = installWaClientPlugins;
 const types_1 = require("../plugins/types");
 const primitives_1 = require("../../util/primitives");
+const PLUGIN_REGISTRY = Symbol('waClientPluginRegistry');
+/**
+ * Per-client store for exposed-plugin state that must survive a
+ * disconnect/connect cycle. Each `exposeAs` property is defined on the client
+ * exactly once (a non-configurable getter reading `instances`); reinstalls
+ * only repopulate the slot, so plugins can be torn down on disconnect and
+ * rebuilt on the next connect without redefining reserved members.
+ */
+function getPluginRegistry(client) {
+    const holder = client;
+    const existing = holder[PLUGIN_REGISTRY];
+    if (existing) {
+        return existing;
+    }
+    const registry = { instances: new Map(), exposedDefined: new Set() };
+    Object.defineProperty(client, PLUGIN_REGISTRY, {
+        value: registry,
+        enumerable: false,
+        configurable: false,
+        writable: false
+    });
+    return registry;
+}
 /**
  * Installs {@link WaClientOptions.plugins} on `client`. Returns a dispose
- * function invoked by {@link WaClient.disconnect}.
+ * function invoked by {@link WaClient.disconnect}. Safe to call again after a
+ * dispose to reinstall the same plugins on reconnect.
  */
 function installWaClientPlugins(client, input, plugins) {
+    const registry = getPluginRegistry(client);
     const seenIds = new Set();
     const seenExposeAs = new Set();
     const disposeCallbacks = [];
@@ -40,24 +65,32 @@ function installWaClientPlugins(client, input, plugins) {
             logger: input.logger.child({ plugin: plugin.id })
         };
         if ((0, types_1.isWaClientExposePluginDefinition)(plugin)) {
-            if (seenExposeAs.has(plugin.exposeAs)) {
-                throw new Error(`duplicate wa client plugin exposeAs: ${plugin.exposeAs}`);
+            const exposeAs = plugin.exposeAs;
+            if (seenExposeAs.has(exposeAs)) {
+                throw new Error(`duplicate wa client plugin exposeAs: ${exposeAs}`);
             }
-            seenExposeAs.add(plugin.exposeAs);
-            if (plugin.exposeAs in client) {
-                throw new Error(`wa client plugin exposeAs "${plugin.exposeAs}" collides with a reserved client member`);
+            seenExposeAs.add(exposeAs);
+            if (!registry.exposedDefined.has(exposeAs)) {
+                if (exposeAs in client) {
+                    throw new Error(`wa client plugin exposeAs "${exposeAs}" collides with a reserved client member`);
+                }
+                registry.exposedDefined.add(exposeAs);
+                Object.defineProperty(client, exposeAs, {
+                    get: () => registry.instances.get(exposeAs),
+                    enumerable: true,
+                    configurable: false
+                });
             }
             const instance = plugin.setup(pluginCtx);
-            Object.defineProperty(client, plugin.exposeAs, {
-                get: () => instance,
-                enumerable: true,
-                configurable: false
+            registry.instances.set(exposeAs, instance);
+            registerDispose(() => {
+                registry.instances.delete(exposeAs);
             });
             if (plugin.dispose) {
                 const dispose = plugin.dispose;
                 registerDispose(() => dispose(instance, pluginCtx));
             }
-            pluginCtx.logger.debug('wa client plugin installed', { exposeAs: plugin.exposeAs });
+            pluginCtx.logger.debug('wa client plugin installed', { exposeAs });
         }
         else {
             plugin.setup(pluginCtx);

package/dist/client/types.d.ts

@@ -1,8 +1,10 @@
 import type { AppStateCollectionName } from '../appstate/types';
 import type { DataForKey, WaAppstateActionKey, WaAppstateIndexArgs } from '../appstate-spec';
+import type { WaShortcakeAssertionSigner } from '../auth/pairing/WaShortcakeFlow';
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthDangerousOptions, WaAuthSocketOptions } from '../auth/types';
 import type { WaCallGroupParticipant, WaCallType } from './events/call';
 import type { IncomingPresenceType, PresenceLastSeen } from './events/presence';
+import type { CompanionHostPersistence } from './persistence/companion-host';
 import type { WaClientPluginDefinition } from './plugins/types';
 import type { WaMediaProcessor } from '../media/processor';
 import type { WaLinkPreviewOptions } from '../message/addons/link-preview/types';
@@ -82,6 +84,16 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * tests or pinning a specific edge.
      */
     readonly chatSocketUrls?: readonly string[];
+    /**
+     * Companion-hosting config for a mobile-primary session (see
+     * {@link WaClient.mobile}). `persistence` survives the ADV epoch across
+     * restarts (without it, relinking breaks previously linked devices);
+     * `includePem` adds the experimental `<pem>` node to the pair-device upload.
+     */
+    readonly companionHost?: {
+        readonly persistence?: CompanionHostPersistence;
+        readonly includePem?: boolean;
+    };
     /** Default timeout (ms) for IQ queries. Defaults to `WA_DEFAULTS.IQ_TIMEOUT_MS` (60s). */
     readonly iqTimeoutMs?: number;
     /** Default timeout (ms) for raw node `query()` calls when none is passed. */
@@ -118,8 +130,11 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * Automatically reconnect when the server rejects the noise handshake
      * with HTTP 405 / `failure_client_too_old`. On every 405 the client
      * logs a warning asking you to upgrade zapo, fetches the current
-     * version from `web.whatsapp.com` via `fetchLatestWaWebVersion()`,
-     * swaps it in for the next connect, and retries. Off by default.
+     * version, swaps it in for the next connect, and retries. Off by
+     * default. Web sessions fetch the WA Web version via
+     * `fetchLatestWaWebVersion()` (swapped in as the connect `version`);
+     * mobile sessions fetch the Android app version via
+     * `fetchLatestWaMobileVersion()` (swapped in as `deviceInfo.appVersion`).
      */
     readonly recoverFromClientTooOld?: boolean;
     /**
@@ -140,6 +155,7 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * Chat-event emission tuning. `emitSnapshotMutations: true` re-emits
      * `app_state_mutation` events for every mutation seen during a snapshot
      * sync (off by default – those mutations represent historical state).
+     * This client's own outbound app-state actions surface on `mutation_send`.
      */
     readonly chatEvents?: {
         readonly emitSnapshotMutations?: boolean;
@@ -193,6 +209,14 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * disables a security check the production code path enforces.
      */
     readonly dangerous?: WaClientDangerousOptions;
+    /**
+     * External WebAuthn signer. Configuring it enables handling a server-forced
+     * passkey ("Shortcake") prologue – e.g. when the server demands a passkey
+     * right after a successful pairing-code `companion_finish`. Called with the
+     * server's request options; returns the assertion + credential id. The
+     * credential source (real/virtual authenticator) stays outside the library.
+     */
+    readonly signPasskeyAssertion?: WaShortcakeAssertionSigner;
 }
 export interface WaClientDangerousOptions extends WaAuthDangerousOptions {
     /**
@@ -531,6 +555,22 @@ export interface WaIncomingMessageEvent extends Omit<WaIncomingBaseEvent, 'chatJ
     readonly pushName?: string;
     readonly message?: Proto.IMessage;
 }
+/**
+ * An outbound message this client sent, surfaced with its decrypted
+ * {@link Proto.IMessage} – the symmetric counterpart to
+ * {@link WaIncomingMessageEvent}. Fires from {@link WaMessageCoordinator.send}
+ * as the stanza is built, so plugins/loggers can observe outgoing content
+ * (forwards, reactions, polls, media) that the encrypted `<message>` on the
+ * wire does not reveal.
+ */
+export interface WaOutgoingMessageEvent {
+    /** Destination jid (chat / group / status). */
+    readonly to: string;
+    /** Outgoing stanza id, when assigned. */
+    readonly id?: string;
+    /** The decrypted message proto being sent. */
+    readonly message: Proto.IMessage;
+}
 export interface WaIncomingProtocolMessageEvent extends WaIncomingMessageEvent {
     readonly protocolMessage: Proto.Message.IProtocolMessage;
 }
@@ -992,7 +1032,7 @@ export interface WaHistorySyncChunkEvent {
     /** Server-reported progress, 0–100. */
     readonly progress?: number;
 }
-export type WaAppStateMutationSource = 'snapshot' | 'patch';
+export type WaAppStateMutationSource = 'snapshot' | 'patch' | 'local';
 type MutationEventBase = {
     readonly source: WaAppStateMutationSource;
     readonly collection: AppStateCollectionName;
@@ -1013,6 +1053,12 @@ export type WaAppStateMutationEvent = {
         readonly operation: 'remove';
     } & MutationEventBase & WaAppstateIndexArgs<K>);
 }[WaAppstateActionKey];
+/**
+ * Listener shared by the inbound `mutation` and outbound `mutation_send`
+ * events. A single named alias so the (large) `WaAppStateMutationEvent` union
+ * is referenced once by the event map rather than expanded per event.
+ */
+type WaAppStateMutationListener = (event: WaAppStateMutationEvent) => void;
 export type WaConnectionEvent = {
     readonly status: 'open';
     readonly reason: WaConnectionOpenReason;
@@ -1071,6 +1117,16 @@ export interface WaClientEventMap {
     readonly auth_paired: (event: {
         readonly credentials: WaAuthCredentials;
     }) => void;
+    /**
+     * The server is forcing a passkey (Shortcake) to link this device – emitted
+     * when the server pushes the prologue request. `hasSigner` is `true` when a
+     * `signPasskeyAssertion` is configured (the handshake proceeds) and `false`
+     * when none is set (the request is acked but the link cannot complete
+     * headless, so the user should be told a passkey is required).
+     */
+    readonly auth_passkey_required: (event: {
+        readonly hasSigner: boolean;
+    }) => void;
     /**
      * Connection-state transitions: `'open'` (handshake + auth complete),
      * `'connecting'`, or `'close'` (with a `reason` and optional `code`). The
@@ -1084,6 +1140,13 @@ export interface WaClientEventMap {
      * `options.quote` for threads).
      */
     readonly message: (event: WaIncomingMessageEvent) => void;
+    /**
+     * An outbound message this client is sending, with its decrypted
+     * {@link Proto.IMessage} – the symmetric counterpart to `message`. Lets
+     * plugins/loggers observe outgoing content (forwards, reactions, polls,
+     * media) the encrypted wire stanza hides.
+     */
+    readonly message_send: (event: WaOutgoingMessageEvent) => void;
     /**
      * A decrypted addon (poll vote, reaction, edit, comment, ...) attached to
      * a previous message. Fires unless `addons.autoDecrypt` is explicitly
@@ -1143,11 +1206,20 @@ export interface WaClientEventMap {
     /** Profile/group/community picture change notification – the new picture must still be fetched explicitly. */
     readonly picture: (event: WaPictureEvent) => void;
     /**
-     * A parsed app-state mutation crossed the sync boundary – chat mute/star/
-     * read/pin/archive/contact/label/etc. Use the discriminator
-     * (`event.action`) to branch on the mutation kind.
+     * A parsed app-state mutation arriving from a sync – chat mute/star/read/
+     * pin/archive/contact/label/etc. changed on another device. Inbound only;
+     * this client's own outbound actions surface on `mutation_send`. Use the
+     * discriminator (`event.schema`) to branch on the mutation kind.
+     */
+    readonly mutation: WaAppStateMutationListener;
+    /**
+     * An app-state action this client is sending (mute/star/read/pin/archive/
+     * clear/delete/…) surfaced at action time – the outbound counterpart to
+     * `mutation`, symmetric to how `message_send` pairs with `message`.
+     * `event.source` is always `'local'`. Optimistic: emitted as the mutation
+     * is enqueued, before the server flush confirms it.
      */
-    readonly mutation: (event: WaAppStateMutationEvent) => void;
+    readonly mutation_send: WaAppStateMutationListener;
     /**
      * One chunk of history-sync data, fired both during the initial
      * bootstrap that the primary device pushes after pairing and for any
@@ -1185,6 +1257,17 @@ export interface WaClientEventMap {
      * `mobileTransport`.
      */
     readonly mobile_account_takeover_notice: (event: WaAccountTakeoverNoticeEvent) => void;
+    /** A companion device was linked from this mobile-primary account. */
+    readonly companion_host_linked: (result: {
+        readonly deviceJid: string;
+        readonly keyIndex: number;
+    }) => void;
+    /** A hosted companion device was revoked / unlinked. */
+    readonly companion_host_revoked: (payload: {
+        readonly deviceJid: string;
+    }) => void;
+    /** A companion-host link or provisioning operation failed. */
+    readonly companion_host_error: (error: Error) => void;
     /** **debug** – the success node closing the noise handshake; emitted before `connection: { status: 'open' }`. */
     readonly debug_connection_success: (event: {
         readonly node: BinaryNode;

package/dist/esm/auth/WaAuthClient.js

@@ -1,10 +1,12 @@
 import { buildCommsConfig, loadOrCreateCredentials, persistCredentials } from './credentials-flow.js';
 import { WaPairingFlow } from './pairing/WaPairingFlow.js';
 import { WaQrFlow } from './pairing/WaQrFlow.js';
-import { getWaCompanionPlatformId, WA_DEFAULTS } from '../protocol/constants.js';
+import { WaShortcakeFlow } from './pairing/WaShortcakeFlow.js';
+import { resolveWaDeviceIdentity, WA_NOTIFICATION_TYPES } from '../protocol/constants.js';
+import { buildAckNode } from '../transport/node/builders/global.js';
+import { resolveDevicePropsPlatformType } from '../transport/noise/WaClientPayload.js';
 import { uint8Equal } from '../util/bytes.js';
 import { toError } from '../util/primitives.js';
-import { getRuntimeOsDisplayName } from '../util/runtime.js';
 /**
  * Owns the auth/pairing lifecycle and persistence of {@link WaAuthCredentials}.
  * Exposed as `client.auth` on a {@link WaClient}.
@@ -17,12 +19,8 @@ import { getRuntimeOsDisplayName } from '../util/runtime.js';
 export class WaAuthClient {
     constructor(options, deps) {
         this.versionOverride = null;
-        const deviceBrowser = options.deviceBrowser ?? WA_DEFAULTS.DEVICE_BROWSER;
-        const device = Object.freeze({
-            browser: deviceBrowser,
-            osDisplayName: options.deviceOsDisplayName ?? getRuntimeOsDisplayName(),
-            platform: options.devicePlatform ?? getWaCompanionPlatformId(deviceBrowser)
-        });
+        this.mobileAppVersionOverride = null;
+        const device = resolveWaDeviceIdentity(options);
         this.options = Object.freeze({
             ...options,
             deviceBrowser: device.browser,
@@ -59,6 +57,23 @@ export class WaAuthClient {
             },
             dangerous: options.dangerous
         });
+        this.socket = deps.socket;
+        const signAssertion = deps.callbacks?.signPasskeyAssertion;
+        this.shortcakeFlow = signAssertion
+            ? new WaShortcakeFlow({
+                logger: this.logger,
+                socket: {
+                    sendNode: deps.socket.sendNode,
+                    query: (node, timeoutMs) => deps.socket.query(node, timeoutMs)
+                },
+                signAssertion,
+                auth: {
+                    getCredentials: () => this.credentials,
+                    updateCredentials: this.updateCredentials.bind(this)
+                },
+                deviceType: resolveDevicePropsPlatformType(device.browser)
+            })
+            : null;
     }
     /**
      * Returns a snapshot of auth readiness flags (connection, registration,
@@ -104,12 +119,15 @@ export class WaAuthClient {
         this.logger.trace('auth client building comms config');
         const override = this.versionOverride;
         this.versionOverride = null;
+        const mobileAppVersionOverride = this.mobileAppVersionOverride;
+        this.mobileAppVersionOverride = null;
         return buildCommsConfig(this.logger, this.requireCredentials(), socketOptions, {
             deviceBrowser: this.options.deviceBrowser,
             deviceOsDisplayName: this.options.deviceOsDisplayName,
             requireFullSync: this.options.requireFullSync,
             version: override ?? this.options.version,
             mobileTransport: this.options.mobileTransport,
+            mobileAppVersionOverride: mobileAppVersionOverride ?? undefined,
             noiseTrustedRootCa: overrides.noiseTrustedRootCa,
             disableNoiseCertificateChainVerification: overrides.disableNoiseCertificateChainVerification ??
                 this.options.dangerous?.disableNoiseCertificateChainVerification
@@ -125,12 +143,24 @@ export class WaAuthClient {
     setNextConnectVersion(version) {
         this.versionOverride = version;
     }
+    /**
+     * One-shot override for the mobile `deviceInfo.appVersion` on the next
+     * {@link buildCommsConfig} call, then clears. The mobile transport reads
+     * its version from `deviceInfo.appVersion` (the login payload), not the
+     * `version` string, so {@link setNextConnectVersion} has no effect on a
+     * mobile session. Used by the `recoverFromClientTooOld` auto-retry to
+     * inject a fresh Android app version without mutating the user's options.
+     */
+    setNextConnectMobileAppVersion(appVersion) {
+        this.mobileAppVersionOverride = appVersion;
+    }
     /** Clears the in-memory QR and pairing sessions without touching storage. */
     // eslint-disable-next-line @typescript-eslint/require-await
     async clearTransientState() {
         this.logger.trace('auth client clear transient state');
         this.qrFlow.clear();
         this.pairingFlow.clearSession();
+        this.shortcakeFlow?.clearSession();
     }
     /**
      * Wipes credentials from memory **and** from the auth store. Does
@@ -289,9 +319,35 @@ export class WaAuthClient {
     }
     /** Dispatcher: returns `true` when `node` is a link-code companion notification. */
     async handleLinkCodeNotification(node) {
+        const type = node.attrs.type;
+        if (type === WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST ||
+            type === WA_NOTIFICATION_TYPES.CRSC_CONTINUATION) {
+            return this.runHandled(() => this.handleShortcakeNotification(node));
+        }
         this.logger.trace('auth client handleLinkCodeNotification', { id: node.attrs.id });
         return this.runHandled(() => this.pairingFlow.handleLinkCodeNotification(node));
     }
+    /**
+     * Handles the server-forced passkey (Shortcake) prologue. With a configured
+     * `signPasskeyAssertion` the full handshake runs; without one we just ack
+     * and warn instead of silently stalling – which is what happens today when
+     * the server demands a passkey after a successful pairing-code
+     * `companion_finish`.
+     */
+    async handleShortcakeNotification(node) {
+        if (node.attrs.type === WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST) {
+            this.callbacks.onPasskeyRequired?.(this.shortcakeFlow !== null);
+        }
+        if (this.shortcakeFlow) {
+            return this.shortcakeFlow.handleIncomingNotification(node);
+        }
+        if (node.attrs.type === WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST) {
+            this.logger.warn('auth client: server requested passkey prologue but no signPasskeyAssertion configured', { id: node.attrs.id });
+            await this.socket.sendNode(buildAckNode({ kind: 'notification', node }));
+            return true;
+        }
+        return false;
+    }
     /** Dispatcher: returns `true` when `node` is a companion-registration refresh notification. */
     async handleCompanionRegRefreshNotification(node) {
         this.logger.trace('auth client handleCompanionRegRefreshNotification', {