zapo-js 1.2.1 → 1.4.0

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 { WaClientPluginDefinition } from './plugins/types';
 import type { WaMediaProcessor } from '../media/processor';
 import type { WaLinkPreviewOptions } from '../message/addons/link-preview/types';
 import type { WaQuoteRef, WaSendContextInfo } from '../message/context-info';
@@ -173,6 +175,11 @@ export interface WaClientOptions extends WaAuthClientOptions, WaAuthSocketOption
      * default auto-fetch globally.
      */
     readonly linkPreview?: WaLinkPreviewOptions;
+    /**
+     * Optional client plugins – behavior hooks and/or coordinators exposed at
+     * `client[exposeAs]`. See {@link defineWaClientPlugin}.
+     */
+    readonly plugins?: readonly WaClientPluginDefinition[];
     /**
      * Test-only overrides intended for running against a fake server.
      *
@@ -187,6 +194,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 {
     /**
@@ -1065,6 +1080,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

package/dist/esm/auth/WaAuthClient.js

@@ -1,7 +1,10 @@
 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 { getWaCompanionPlatformId, WA_DEFAULTS, 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';
@@ -59,6 +62,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(deviceBrowser)
+            })
+            : null;
     }
     /**
      * Returns a snapshot of auth readiness flags (connection, registration,
@@ -131,6 +151,7 @@ export class WaAuthClient {
         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 +310,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', {

package/dist/esm/auth/pairing/WaShortcakeFlow.js

@@ -0,0 +1,206 @@
+import { decodePrimaryEphemeralIdentity, deriveEncryptionKey, deriveVerificationCode, encryptPairingRequest, generateCompanionEphemeralIdentity } from '../pairing/shortcake-crypto.js';
+import { hkdf, hmacSha256Sign, randomBytesAsync } from '../../crypto/index.js';
+import { proto } from '../../proto.js';
+import { WA_DEFAULTS, WA_NODE_TAGS, WA_NOTIFICATION_TYPES } from '../../protocol/constants.js';
+import { buildAckNode } from '../../transport/node/builders/global.js';
+import { buildGetPasskeyRequestOptionsRequestNode, buildSetCompanionNonceRequestNode, buildSetEncryptedPairingRequestRequestNode, buildSetPasskeyPrologueRequestNode, buildShortcakeGetRefRequestNode } from '../../transport/node/builders/shortcake.js';
+import { decodeNodeContentUtf8OrBytes, findNodeChild } from '../../transport/node/helpers.js';
+import { assertIqResult } from '../../transport/node/query.js';
+import { TEXT_DECODER, TEXT_ENCODER } from '../../util/bytes.js';
+/** HKDF info for the pairing handoff HMAC key (derived from the ADV secret). */
+const HANDOFF_KEY_INFO = TEXT_ENCODER.encode('shortcake-passkey-handoff-v1');
+const HANDOFF_KEY_TTL_MS = 5 * 60 * 1000;
+const Stage = Object.freeze({
+    Idle: 'idle',
+    WaitingForPrimaryIdentity: 'waiting_for_primary_identity',
+    WaitingForConfirmation: 'waiting_for_confirmation',
+    WaitingForPairing: 'waiting_for_pairing'
+});
+/**
+ * Drives the companion side of the WhatsApp "Shortcake" passkey-linking
+ * handshake (the `xmlns="md"` IQ exchange + commit/reveal ECDH). It owns the
+ * wire protocol and crypto only; the WebAuthn assertion and the registration
+ * payload are injected by the caller.
+ */
+export class WaShortcakeFlow {
+    constructor(options) {
+        this.opts = options;
+        this.session = null;
+        this.handoffKey = null;
+    }
+    hasSession() {
+        return this.session !== null;
+    }
+    clearSession() {
+        this.session = null;
+        this.handoffKey = null;
+    }
+    /**
+     * Runs the prologue: fetch the request options, obtain the WebAuthn
+     * assertion (external), fetch the ref, build the companion ephemeral
+     * identity + commitment, and send the `passkey_prologue` IQ.
+     */
+    async executePrologue(args = {}) {
+        const deviceType = this.opts.deviceType ?? proto.DeviceProps.PlatformType.CHROME;
+        const requestOptions = args.requestOptions ?? (await this.requestPasskeyRequestOptions());
+        const assertion = await this.opts.signAssertion(requestOptions);
+        const ref = await this.requestRef();
+        const companion = await generateCompanionEphemeralIdentity({ ref, deviceType });
+        let pairingHandoffProof = args.pairingHandoffProof;
+        const handoffKey = this.handoffKey;
+        this.handoffKey = null;
+        if (pairingHandoffProof === undefined &&
+            handoffKey !== null &&
+            Date.now() - handoffKey.ts < HANDOFF_KEY_TTL_MS) {
+            pairingHandoffProof = hmacSha256Sign(handoffKey.hmac, companion.prologuePayloadBytes);
+        }
+        const skipHandoffUx = pairingHandoffProof !== undefined;
+        const response = await this.opts.socket.query(buildSetPasskeyPrologueRequestNode({
+            credentialId: assertion.credentialId,
+            webauthnAssertion: assertion.webauthnAssertion,
+            prologuePayload: companion.prologuePayloadBytes,
+            pairingHandoffProof
+        }), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake set-passkey-prologue');
+        this.session = {
+            companion,
+            ref,
+            deviceType,
+            skipHandoffUx,
+            stage: Stage.WaitingForPrimaryIdentity,
+            encryptionKey: null,
+            verificationCode: null
+        };
+        this.opts.logger.debug('shortcake prologue sent', { ref, skipHandoffUx });
+        this.opts.callbacks?.emitPrologueSent?.();
+    }
+    /**
+     * Routes the two server-pushed Shortcake notifications. Returns `true` when
+     * the notification was a Shortcake one (and was consumed):
+     * - `passkey_prologue_request` kicks the flow off (server forces passkey,
+     *   often right after a pairing-code `companion_finish`); the WebAuthn
+     *   options are usually embedded.
+     * - `crsc_continuation` carries the primary's ephemeral identity.
+     */
+    async handleIncomingNotification(node) {
+        if (node.attrs.type === WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST) {
+            return this.handlePasskeyPrologueRequest(node);
+        }
+        if (node.attrs.type === WA_NOTIFICATION_TYPES.CRSC_CONTINUATION) {
+            return this.handlePrimaryEphemeralIdentity(node);
+        }
+        return false;
+    }
+    async handlePasskeyPrologueRequest(node) {
+        await this.ackNotification(node);
+        await this.stashHandoffKeyAndRotateAdv();
+        const optionsNode = findNodeChild(node, WA_NODE_TAGS.PASSKEY_REQUEST_OPTIONS);
+        const requestOptions = optionsNode
+            ? decodeNodeContentUtf8OrBytes(optionsNode.content, 'shortcake.passkey_request_options')
+            : undefined;
+        this.opts.logger.debug('shortcake prologue requested by server', {
+            embeddedOptions: optionsNode !== undefined
+        });
+        await this.executePrologue({ requestOptions });
+        return true;
+    }
+    /**
+     * Derives a pairing handoff HMAC key from the current ADV secret and rotates
+     * the ADV secret (matching the official clients). The derived key signs the
+     * next prologue's handoff proof; the rotated secret goes into the eventual
+     * `PairingRequest`.
+     */
+    async stashHandoffKeyAndRotateAdv() {
+        const credentials = this.opts.auth.getCredentials();
+        if (!credentials) {
+            return;
+        }
+        this.handoffKey = {
+            hmac: hkdf(credentials.advSecretKey, null, HANDOFF_KEY_INFO, 32),
+            ts: Date.now()
+        };
+        await this.opts.auth.updateCredentials({
+            ...credentials,
+            advSecretKey: await randomBytesAsync(32)
+        });
+    }
+    async handlePrimaryEphemeralIdentity(node) {
+        const child = findNodeChild(node, WA_NODE_TAGS.PRIMARY_EPHEMERAL_IDENTITY);
+        if (!child) {
+            return false;
+        }
+        const session = this.session;
+        if (!session || session.stage !== Stage.WaitingForPrimaryIdentity) {
+            this.opts.logger.warn('shortcake primary identity ignored: no active prologue');
+            await this.ackNotification(node);
+            return true;
+        }
+        await this.ackNotification(node);
+        const primary = decodePrimaryEphemeralIdentity(decodeNodeContentUtf8OrBytes(child.content, 'shortcake.primary_ephemeral_identity'));
+        const nonceResponse = await this.opts.socket.query(buildSetCompanionNonceRequestNode(session.companion.companionNonce), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(nonceResponse, 'shortcake set-companion-nonce');
+        const verificationCode = deriveVerificationCode(session.companion.companionNonce, primary);
+        const encryptionKey = await deriveEncryptionKey({
+            companionPrivKey: session.companion.keyPair.privKey,
+            primaryPublicKey: primary.publicKey,
+            deviceType: session.deviceType,
+            ref: session.ref
+        });
+        session.encryptionKey = encryptionKey;
+        session.verificationCode = verificationCode;
+        session.stage = Stage.WaitingForConfirmation;
+        this.opts.logger.debug('shortcake verification code ready');
+        this.opts.callbacks?.emitVerificationCode?.(verificationCode);
+        await this.confirmVerificationCode();
+        return true;
+    }
+    /** Current verification code, once derived. */
+    getVerificationCode() {
+        return this.session?.verificationCode ?? null;
+    }
+    /**
+     * Confirms the verification code: builds + AES-GCM seals the pairing request
+     * and sends the `encrypted_pairing_request` IQ.
+     */
+    async confirmVerificationCode() {
+        const session = this.session;
+        if (!session || session.stage !== Stage.WaitingForConfirmation || !session.encryptionKey) {
+            throw new Error('shortcake: no verification code awaiting confirmation');
+        }
+        const credentials = this.opts.auth.getCredentials();
+        if (!credentials) {
+            throw new Error('shortcake: credentials are not initialized');
+        }
+        const plaintext = proto.PairingRequest.encode({
+            companionPublicKey: credentials.noiseKeyPair.pubKey,
+            companionIdentityKey: credentials.registrationInfo.identityKeyPair.pubKey,
+            advSecret: credentials.advSecretKey
+        }).finish();
+        const envelope = await encryptPairingRequest(session.encryptionKey, plaintext);
+        const response = await this.opts.socket.query(buildSetEncryptedPairingRequestRequestNode(envelope), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake set-encrypted-pairing-request');
+        session.stage = Stage.WaitingForPairing;
+        this.opts.logger.debug('shortcake encrypted pairing request sent');
+    }
+    async requestPasskeyRequestOptions() {
+        const response = await this.opts.socket.query(buildGetPasskeyRequestOptionsRequestNode(), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake get-passkey-request-options');
+        const optionsNode = findNodeChild(response, WA_NODE_TAGS.PASSKEY_REQUEST_OPTIONS);
+        if (!optionsNode) {
+            throw new Error('shortcake: get-passkey-request-options response missing options');
+        }
+        return decodeNodeContentUtf8OrBytes(optionsNode.content, 'shortcake.passkey_request_options');
+    }
+    async requestRef() {
+        const response = await this.opts.socket.query(buildShortcakeGetRefRequestNode(), WA_DEFAULTS.IQ_TIMEOUT_MS);
+        assertIqResult(response, 'shortcake get-ref');
+        const refNode = findNodeChild(response, WA_NODE_TAGS.REF);
+        if (!refNode) {
+            throw new Error('shortcake: get-ref response missing ref');
+        }
+        return TEXT_DECODER.decode(decodeNodeContentUtf8OrBytes(refNode.content, 'shortcake.ref'));
+    }
+    async ackNotification(node) {
+        await this.opts.socket.sendNode(buildAckNode({ kind: 'notification', node }));
+    }
+}

package/dist/esm/auth/pairing/pairing-code-crypto.js

@@ -5,7 +5,7 @@ import { concatBytes, TEXT_ENCODER } from '../../util/bytes.js';
 const CROCKFORD_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTVWXYZ';
 export const PBKDF2_ITERATIONS = 2 << 16;
 const PAIRING_AES_KEY_BYTES = 32;
-function bytesToCrockford(bytes) {
+export function encodeBytesToCrockford(bytes) {
     let bitCount = 0;
     let value = 0;
     let out = '';
@@ -42,7 +42,7 @@ export async function createCompanionHello(options = {}) {
         randomBytesAsync(16),
         normalizedCustomCode !== null ? Promise.resolve(null) : randomBytesAsync(5)
     ]);
-    const pairingCode = normalizedCustomCode ?? bytesToCrockford(codeBytes);
+    const pairingCode = normalizedCustomCode ?? encodeBytesToCrockford(codeBytes);
     const cipherKey = await pbkdf2Sha256(TEXT_ENCODER.encode(pairingCode), salt, PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
     const encrypted = aesCtrEncrypt(cipherKey, counter, companionEphemeralKeyPair.pubKey);
     return {

package/dist/esm/auth/pairing/shortcake-crypto.js

@@ -0,0 +1,99 @@
+import { encodeBytesToCrockford } from '../pairing/pairing-code-crypto.js';
+import { aesGcmEncrypt, hkdf, randomBytesAsync, sha256 } from '../../crypto/index.js';
+import { X25519 } from '../../crypto/curves/X25519.js';
+import { proto } from '../../proto.js';
+import { concatBytes, TEXT_ENCODER } from '../../util/bytes.js';
+/**
+ * Cryptographic core of the WhatsApp "Shortcake" companion-linking protocol
+ * (the device-link flow the official clients call CRSC / Shortcake).
+ *
+ * This module implements ONLY the wire/crypto half: ephemeral X25519 key
+ * exchange, the commit-reveal nonce, the verification code, and the AES-GCM
+ * pairing envelope. The WebAuthn/passkey assertion that gates the prologue is
+ * NOT produced here – it is an opaque input supplied by the caller (so the
+ * credential source stays out of the protocol layer).
+ *
+ * Mirrors `WAWebShortcakeLinkingAlgorithm` from the web client.
+ */
+const NONCE_BYTES = 32;
+const VERIFICATION_CODE_BYTES = 5;
+const GCM_IV_BYTES = 12;
+const ENCRYPTION_KEY_BYTES = 32;
+const EPHEMERAL_PUBLIC_KEY_BYTES = 32;
+/** HKDF `info` for the pairing-request encryption key. */
+const ENCRYPTION_KEY_INFO = TEXT_ENCODER.encode('Pairing Information Encryption Key');
+/**
+ * Generates the companion's ephemeral identity + commitment for a Shortcake
+ * prologue. The companion publishes a commitment to its nonce now and reveals
+ * the nonce later (after the primary's identity arrives) so the primary cannot
+ * grind the verification code.
+ */
+export async function generateCompanionEphemeralIdentity(args) {
+    const [keyPair, companionNonce] = await Promise.all([
+        X25519.generateKeyPair(),
+        randomBytesAsync(NONCE_BYTES)
+    ]);
+    const companionEphemeralIdentityBytes = proto.CompanionEphemeralIdentity.encode({
+        publicKey: keyPair.pubKey,
+        deviceType: args.deviceType,
+        ref: args.ref
+    }).finish();
+    const commitmentHash = sha256(concatBytes([companionEphemeralIdentityBytes, companionNonce]));
+    const prologuePayloadBytes = proto.ProloguePayload.encode({
+        companionEphemeralIdentity: companionEphemeralIdentityBytes,
+        commitment: { hash: commitmentHash }
+    }).finish();
+    return {
+        keyPair,
+        companionNonce,
+        companionEphemeralIdentityBytes,
+        commitmentHash,
+        prologuePayloadBytes
+    };
+}
+/** Parses + validates a `PrimaryEphemeralIdentity` proto from the primary. */
+export function decodePrimaryEphemeralIdentity(bytes) {
+    const decoded = proto.PrimaryEphemeralIdentity.decode(bytes);
+    const publicKey = decoded.publicKey;
+    const nonce = decoded.nonce;
+    if (!publicKey || publicKey.length !== EPHEMERAL_PUBLIC_KEY_BYTES) {
+        throw new Error('shortcake: PrimaryEphemeralIdentity.publicKey must be 32 bytes');
+    }
+    if (!nonce || nonce.length !== NONCE_BYTES) {
+        throw new Error('shortcake: PrimaryEphemeralIdentity.nonce must be 32 bytes');
+    }
+    return { publicKey, nonce };
+}
+/**
+ * Derives the short verification code shown on both devices:
+ * `Crockford32( primaryNonce[0..5] XOR SHA-256(companionNonce ‖ primaryPubKey)[0..5] )`.
+ */
+export function deriveVerificationCode(companionNonce, primary) {
+    const digest = sha256(concatBytes([companionNonce, primary.publicKey]));
+    const code = new Uint8Array(VERIFICATION_CODE_BYTES);
+    for (let i = 0; i < VERIFICATION_CODE_BYTES; i += 1) {
+        code[i] = primary.nonce[i] ^ digest[i];
+    }
+    return encodeBytesToCrockford(code);
+}
+/**
+ * Derives the AES-GCM key that protects the pairing request:
+ * `HKDF( X25519(companionPriv, primaryPub), salt="Companion Pairing <deviceType> with ref <ref>", info="Pairing Information Encryption Key" )`.
+ */
+export async function deriveEncryptionKey(args) {
+    const shared = await X25519.scalarMult(args.companionPrivKey, args.primaryPublicKey);
+    const salt = TEXT_ENCODER.encode(`Companion Pairing ${String(args.deviceType)} with ref ${args.ref}`);
+    return hkdf(shared, salt, ENCRYPTION_KEY_INFO, ENCRYPTION_KEY_BYTES);
+}
+/**
+ * Encrypts the pairing request plaintext under the derived key and returns the
+ * encoded `EncryptedPairingRequest` proto (random 12-byte IV).
+ */
+export async function encryptPairingRequest(encryptionKey, plaintext) {
+    if (encryptionKey.length !== ENCRYPTION_KEY_BYTES) {
+        throw new Error('shortcake: encryption key must be 32 bytes');
+    }
+    const iv = await randomBytesAsync(GCM_IV_BYTES);
+    const encryptedPayload = aesGcmEncrypt(encryptionKey, iv, plaintext);
+    return proto.EncryptedPairingRequest.encode({ encryptedPayload, iv }).finish();
+}

package/dist/esm/client/WaClient.js

@@ -3,6 +3,7 @@ import { createIgnoreKeyFilter, validateIgnoreKey } from './messaging/ignore-key
 import { runHistorySyncNotification } from './persistence/history-sync.js';
 import { persistIncomingMailboxEntities } from './persistence/mailbox.js';
 import { WriteBehindPersistence } from './persistence/WriteBehindPersistence.js';
+import { installWaClientPlugins } from './plugins/install.js';
 import { buildWaClientDependencies, resolveWaClientBase } from './WaClientFactory.js';
 import { ConsoleLogger } from '../infra/log/ConsoleLogger.js';
 import { proto } from '../proto.js';
@@ -19,55 +20,8 @@ const SYNC_RELATED_PROTOCOL_TYPES = new Set([
     proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_MESSAGE,
     proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_RESPONSE_MESSAGE
 ]);
-/**
- * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
- * coordinators (accessible via getters such as {@link message}, {@link group},
- * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
- *
- * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
- * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
- * then use the coordinator getters to drive the session. Call {@link disconnect}
- * to shut down cleanly or {@link logout} to remove the companion device.
- *
- * @example
- * ```ts
- * import { createPinoLogger, createStore, WaClient } from '..'
- * import { createSqliteStore } from '@zapo-js/store-sqlite'
- *
- * const store = createStore({
- *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
- *     providers: {
- *         auth: 'sqlite',
- *         signal: 'sqlite',
- *         preKey: 'sqlite',
- *         session: 'sqlite',
- *         identity: 'sqlite',
- *         senderKey: 'sqlite',
- *         appState: 'sqlite',
- *         privacyToken: 'sqlite',
- *         messages: 'sqlite',
- *         threads: 'sqlite',
- *         contacts: 'sqlite'
- *     }
- * })
- *
- * const client = new WaClient(
- *     { store, sessionId: 'default' },
- *     await createPinoLogger({ level: 'info', pretty: true })
- * )
- *
- * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
- * client.on('connection', (event) => console.log('connection', event))
- * client.on('message', async (event) => {
- *     if (event.message?.conversation === 'ping') {
- *         await client.message.send(event.chatJid!, 'pong')
- *     }
- * })
- *
- * await client.connect()
- * ```
- */
-export class WaClient extends EventEmitter {
+/** @internal Implementation backing the exported {@link WaClient}. */
+class WaClientImpl extends EventEmitter {
     /**
      * @param options Client configuration (store, transport, addons, history...).
      * @param logger  Optional structured logger. Defaults to a `ConsoleLogger('info')`.
@@ -78,6 +32,7 @@ export class WaClient extends EventEmitter {
         this.acceptingIncomingEvents = true;
         this.activeIncomingHandlers = 0;
         this.incomingHandlersDrainedWaiters = [];
+        this.disposePlugins = null;
         const base = resolveWaClientBase(options, logger);
         this.options = base.options;
         this.logger = base.logger;
@@ -115,6 +70,13 @@ export class WaClient extends EventEmitter {
         this.deps = dependencies;
         this.appStateSync = dependencies.appStateSync;
         this.mediaTransfer = dependencies.mediaTransfer;
+        this.disposePlugins = installWaClientPlugins(this, {
+            options: this.options,
+            logger: this.logger,
+            stores: this.stores,
+            deps: this.deps,
+            queryWithContext: this.queryWithContext.bind(this)
+        }, this.options.plugins ?? []);
         this.bindNodeTransportEvents();
         this.on('connection', (event) => {
             if (event.status !== 'close')
@@ -381,6 +343,11 @@ export class WaClient extends EventEmitter {
                 remaining: writeBehindFlush.remaining
             });
         }
+        if (this.disposePlugins) {
+            const dispose = this.disposePlugins;
+            this.disposePlugins = null;
+            await dispose();
+        }
         await this.deps.connectionManager.disconnect();
         this.emit('connection', {
             status: 'close',
@@ -603,3 +570,57 @@ export class WaClient extends EventEmitter {
         this.emit('debug_client_error', { error });
     }
 }
+/**
+ * Top-level WhatsApp client. Owns the transport, auth, signal, and per-feature
+ * coordinators (accessible via getters such as {@link message}, {@link group},
+ * {@link newsletter}, etc.) and re-emits every {@link WaClientEventMap} event.
+ *
+ * Lifecycle: construct with {@link WaClientOptions}, call {@link connect} to
+ * open the socket, react to `connection`/`auth_qr`/`auth_pairing_code` events,
+ * then use the coordinator getters to drive the session. Call {@link disconnect}
+ * to shut down cleanly or {@link logout} to remove the companion device.
+ *
+ * Pass `plugins` to expose plugin getters and events on the returned client,
+ * typed from the values you pass: e.g. `plugins: [voipPlugin()]` adds
+ * `client.voip` and the `voip_*` events, and only then. See
+ * {@link WaClientConstructor}.
+ *
+ * @example
+ * ```ts
+ * import { createPinoLogger, createStore, WaClient } from '..'
+ * import { createSqliteStore } from '@zapo-js/store-sqlite'
+ *
+ * const store = createStore({
+ *     backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
+ *     providers: {
+ *         auth: 'sqlite',
+ *         signal: 'sqlite',
+ *         preKey: 'sqlite',
+ *         session: 'sqlite',
+ *         identity: 'sqlite',
+ *         senderKey: 'sqlite',
+ *         appState: 'sqlite',
+ *         privacyToken: 'sqlite',
+ *         messages: 'sqlite',
+ *         threads: 'sqlite',
+ *         contacts: 'sqlite'
+ *     }
+ * })
+ *
+ * const client = new WaClient(
+ *     { store, sessionId: 'default' },
+ *     await createPinoLogger({ level: 'info', pretty: true })
+ * )
+ *
+ * client.on('auth_qr', ({ qr, ttlMs }) => console.log('scan:', qr, ttlMs))
+ * client.on('connection', (event) => console.log('connection', event))
+ * client.on('message', async (event) => {
+ *     if (event.message?.conversation === 'ping') {
+ *         await client.message.send(event.chatJid!, 'pong')
+ *     }
+ * })
+ *
+ * await client.connect()
+ * ```
+ */
+export const WaClient = WaClientImpl;

package/dist/esm/client/WaClientFactory.js

@@ -348,7 +348,9 @@ export function buildWaClientDependencies(input) {
                 runtime.emitEvent('auth_paired', { credentials });
                 scheduleReconnectAfterPairing();
             },
-            onError: (error) => runtime.handleError(error)
+            onError: (error) => runtime.handleError(error),
+            onPasskeyRequired: (hasSigner) => runtime.emitEvent('auth_passkey_required', { hasSigner }),
+            signPasskeyAssertion: options.signPasskeyAssertion
         }
     });
     const getCurrentCredentials = authClient.getCurrentCredentials.bind(authClient);
@@ -1026,6 +1028,7 @@ export function buildWaClientDependencies(input) {
         signalMissingPreKeysSync,
         signalRotateKey,
         signalSessionSync,
+        sessionResolver,
         authClient,
         messageDispatch,
         messageCoordinator,

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

@@ -61,6 +61,7 @@ export class WaRetryCoordinator {
             signalProtocol: options.signalProtocol,
             sessionResolver: options.sessionResolver,
             getCurrentCredentials: options.getCurrentCredentials,
+            isMobilePrimary: options.isMobilePrimary,
             resolveUserIcdc: options.resolveUserIcdc,
             resolvePrivacyTokenNode: options.resolvePrivacyTokenNode
         });

package/dist/esm/client/plugins/define.js

@@ -0,0 +1,19 @@
+export function defineWaClientPlugin(input) {
+    if ('exposeAs' in input && input.exposeAs !== undefined) {
+        const exposeInput = input;
+        return {
+            id: exposeInput.id,
+            exposeAs: exposeInput.exposeAs,
+            setup: exposeInput.setup,
+            dispose: exposeInput.dispose
+                ? (instance, ctx) => exposeInput.dispose(instance, ctx)
+                : undefined
+        };
+    }
+    const behaviorInput = input;
+    return {
+        id: behaviorInput.id,
+        setup: behaviorInput.setup,
+        dispose: behaviorInput.dispose ? (_instance, ctx) => behaviorInput.dispose(ctx) : undefined
+    };
+}

package/dist/esm/client/plugins/index.js

@@ -0,0 +1,3 @@
+export { defineWaClientPlugin } from '../plugins/define.js';
+export { installWaClientPlugins } from '../plugins/install.js';
+export { isWaClientExposePluginDefinition } from '../plugins/types.js';