zapo-js 1.3.0 → 1.4.0

package/dist/client/types.d.ts

@@ -1,5 +1,6 @@
 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';
@@ -193,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 {
     /**
@@ -1071,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/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);

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/protocol/nodes.js

@@ -50,6 +50,8 @@ export const WA_NODE_TAGS = Object.freeze({
     COUNTRY_CODE: 'country_code',
     DEVICE_IDENTITY: 'device-identity',
     PLATFORM: 'platform',
+    PASSKEY_REQUEST_OPTIONS: 'passkey_request_options',
+    PRIMARY_EPHEMERAL_IDENTITY: 'primary_ephemeral_identity',
     SUBJECT: 'subject',
     BODY: 'body',
     PARTICIPANT: 'participant',

package/dist/esm/protocol/notification.js

@@ -6,7 +6,9 @@ export const WA_NOTIFICATION_TYPES = Object.freeze({
     REGISTRATION: 'registration',
     NEWSLETTER: 'newsletter',
     BUSINESS: 'business',
-    PICTURE: 'picture'
+    PICTURE: 'picture',
+    PASSKEY_PROLOGUE_REQUEST: 'passkey_prologue_request',
+    CRSC_CONTINUATION: 'crsc_continuation'
 });
 export const WA_BUSINESS_NOTIFICATION_TAGS = Object.freeze({
     VERIFIED_NAME: 'verified_name',

package/dist/esm/retry/replay.js

@@ -85,9 +85,9 @@ export class WaRetryReplayService {
     resolveSignedDeviceIdentity(context) {
         const signedIdentity = this.options.getCurrentCredentials()?.signedIdentity;
         if (!signedIdentity) {
-            this.options.logger.warn('retry request missing signed identity for pkmsg envelope', {
-                context
-            });
+            if (!this.options.isMobilePrimary?.()) {
+                this.options.logger.warn('retry request missing signed identity for pkmsg envelope', { context });
+            }
             return undefined;
         }
         return proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
@@ -179,15 +179,7 @@ export class WaRetryReplayService {
             logContext: 'group'
         })) ?? payload.plaintext;
         const encrypted = await this.options.signalProtocol.encryptMessage(requesterAddress, plaintext);
-        let deviceIdentity;
-        if (encrypted.type === 'pkmsg') {
-            const signedIdentity = this.options.getCurrentCredentials()?.signedIdentity;
-            if (!signedIdentity) {
-                this.options.logger.warn('retry request rejected: missing signed identity for pkmsg group retry');
-                return 'ineligible';
-            }
-            deviceIdentity = proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
-        }
+        const deviceIdentity = encrypted.type === 'pkmsg' ? this.resolveSignedDeviceIdentity('group') : undefined;
         const isStatus = isStatusBroadcastJid(payload.to);
         const metaAttrs = {};
         if (isStatus) {

package/dist/esm/transport/node/builders/shortcake.js

@@ -0,0 +1,50 @@
+import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../../protocol/constants.js';
+import { buildIqNode } from '../../node/query.js';
+/**
+ * IQ builders for the WhatsApp "Shortcake" companion-linking protocol
+ * (`xmlns="md"`). Wire shapes mirror the official client's
+ * `WASmaxOutMd…Request` builders. The stanza `id` is assigned by the socket
+ * query layer, matching the other pairing builders.
+ */
+function mdIq(type, content) {
+    return buildIqNode(type, WA_DEFAULTS.HOST_DOMAIN, WA_XMLNS.MD, content);
+}
+/** `<iq type="get" xmlns="md"><passkey_request_options/></iq>` */
+export function buildGetPasskeyRequestOptionsRequestNode() {
+    return mdIq(WA_IQ_TYPES.GET, [
+        { tag: WA_NODE_TAGS.PASSKEY_REQUEST_OPTIONS, attrs: {}, content: undefined }
+    ]);
+}
+/** `<iq type="get" xmlns="md"><ref/></iq>` */
+export function buildShortcakeGetRefRequestNode() {
+    return mdIq(WA_IQ_TYPES.GET, [{ tag: WA_NODE_TAGS.REF, attrs: {}, content: undefined }]);
+}
+/**
+ * `<iq type="set" xmlns="md"><passkey_prologue><credential_id/><webauthn_assertion/>`
+ * `<prologue_payload/>[<pairing_handoff_proof/>]</passkey_prologue></iq>`
+ */
+export function buildSetPasskeyPrologueRequestNode(args) {
+    const children = [
+        { tag: 'credential_id', attrs: {}, content: args.credentialId },
+        { tag: 'webauthn_assertion', attrs: {}, content: args.webauthnAssertion },
+        { tag: 'prologue_payload', attrs: {}, content: args.prologuePayload }
+    ];
+    if (args.pairingHandoffProof) {
+        children.push({
+            tag: 'pairing_handoff_proof',
+            attrs: {},
+            content: args.pairingHandoffProof
+        });
+    }
+    return mdIq(WA_IQ_TYPES.SET, [{ tag: 'passkey_prologue', attrs: {}, content: children }]);
+}
+/** `<iq type="set" xmlns="md"><companion_nonce/></iq>` */
+export function buildSetCompanionNonceRequestNode(companionNonce) {
+    return mdIq(WA_IQ_TYPES.SET, [{ tag: 'companion_nonce', attrs: {}, content: companionNonce }]);
+}
+/** `<iq type="set" xmlns="md"><encrypted_pairing_request/></iq>` */
+export function buildSetEncryptedPairingRequestRequestNode(encryptedPairingRequest) {
+    return mdIq(WA_IQ_TYPES.SET, [
+        { tag: 'encrypted_pairing_request', attrs: {}, content: encryptedPairingRequest }
+    ]);
+}

package/dist/esm/transport/noise/WaClientPayload.js

@@ -33,7 +33,7 @@ function resolveLocale() {
 function defaultWebSubPlatform() {
     return proto.ClientPayload.WebInfo.WebSubPlatform.WEB_BROWSER;
 }
-function resolveDevicePropsPlatformType(deviceBrowser) {
+export function resolveDevicePropsPlatformType(deviceBrowser) {
     const normalized = deviceBrowser?.trim().toLowerCase();
     switch (normalized) {
         case 'chrome':

package/dist/index.d.ts

@@ -30,6 +30,7 @@ export type { WaSendContextInfo } from './message/context-info';
 export type { WaLinkPreviewFetcher, WaLinkPreviewOptions, WaLinkPreviewOverride, WaLinkPreviewResolved, WaLinkPreviewThumbnailBytes, WaLinkPreviewThumbnailInput, WaLinkPreviewThumbnailStream, WaLinkPreviewType } from './message/addons/link-preview/types';
 export type { SignalLidSyncResult } from './signal/api/SignalDeviceSyncApi';
 export type { WaAuthCredentials, WaVersionResolver } from './auth/types';
+export type { WaShortcakeAssertionSigner } from './auth/pairing/WaShortcakeFlow';
 export type { BinaryNode } from './transport/types';
 export { fetchLatestWaWebVersion } from './transport/wa-web-version-fetcher';
 export type { WaFetchLatestWebVersionOptions, WaLatestWebVersion } from './transport/wa-web-version-fetcher';

package/dist/protocol/nodes.d.ts

@@ -50,6 +50,8 @@ export declare const WA_NODE_TAGS: Readonly<{
     readonly COUNTRY_CODE: "country_code";
     readonly DEVICE_IDENTITY: "device-identity";
     readonly PLATFORM: "platform";
+    readonly PASSKEY_REQUEST_OPTIONS: "passkey_request_options";
+    readonly PRIMARY_EPHEMERAL_IDENTITY: "primary_ephemeral_identity";
     readonly SUBJECT: "subject";
     readonly BODY: "body";
     readonly PARTICIPANT: "participant";

package/dist/protocol/nodes.js

@@ -53,6 +53,8 @@ exports.WA_NODE_TAGS = Object.freeze({
     COUNTRY_CODE: 'country_code',
     DEVICE_IDENTITY: 'device-identity',
     PLATFORM: 'platform',
+    PASSKEY_REQUEST_OPTIONS: 'passkey_request_options',
+    PRIMARY_EPHEMERAL_IDENTITY: 'primary_ephemeral_identity',
     SUBJECT: 'subject',
     BODY: 'body',
     PARTICIPANT: 'participant',

package/dist/protocol/notification.d.ts

@@ -7,6 +7,8 @@ export declare const WA_NOTIFICATION_TYPES: Readonly<{
     readonly NEWSLETTER: "newsletter";
     readonly BUSINESS: "business";
     readonly PICTURE: "picture";
+    readonly PASSKEY_PROLOGUE_REQUEST: "passkey_prologue_request";
+    readonly CRSC_CONTINUATION: "crsc_continuation";
 }>;
 export declare const WA_BUSINESS_NOTIFICATION_TAGS: Readonly<{
     readonly VERIFIED_NAME: "verified_name";

package/dist/protocol/notification.js

@@ -9,7 +9,9 @@ exports.WA_NOTIFICATION_TYPES = Object.freeze({
     REGISTRATION: 'registration',
     NEWSLETTER: 'newsletter',
     BUSINESS: 'business',
-    PICTURE: 'picture'
+    PICTURE: 'picture',
+    PASSKEY_PROLOGUE_REQUEST: 'passkey_prologue_request',
+    CRSC_CONTINUATION: 'crsc_continuation'
 });
 exports.WA_BUSINESS_NOTIFICATION_TAGS = Object.freeze({
     VERIFIED_NAME: 'verified_name',

package/dist/retry/replay.d.ts

@@ -12,6 +12,7 @@ export interface WaRetryReplayServiceOptions {
     readonly signalProtocol: SignalProtocol;
     readonly sessionResolver: SignalSessionResolver;
     readonly getCurrentCredentials: () => WaAuthCredentials | null;
+    readonly isMobilePrimary?: () => boolean;
     readonly resolveUserIcdc?: (userJid: string) => Promise<IcdcMeta | null>;
     /**
      * Resolves the trusted-contact (privacy) token node for a recipient user