zapo-js 1.3.0 → 1.5.0

package/dist/appstate/types.d.ts

@@ -28,14 +28,13 @@ export type WaAppStateMutationInput = {
     readonly collection: AppStateCollectionName;
     readonly operation: 'remove';
     readonly index: string;
-    readonly previousValue: Proto.ISyncActionValue;
     readonly version: number;
     readonly timestamp: number;
 };
 export interface WaAppStateMutation {
     readonly collection: AppStateCollectionName;
     readonly operation: 'set' | 'remove';
-    readonly source: 'snapshot' | 'patch';
+    readonly source: 'snapshot' | 'patch' | 'local';
     readonly index: string;
     readonly value: Proto.ISyncActionValue | null;
     readonly version: number;

package/dist/auth/WaAuthClient.d.ts

@@ -1,3 +1,4 @@
+import { type WaShortcakeAssertionSigner } from './pairing/WaShortcakeFlow';
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthSocketOptions, WaSuccessPersistAttributes } from './types';
 import type { Logger } from '../infra/log/types';
 import type { WaAuthStore } from '../store/contracts/auth.store';
@@ -21,6 +22,10 @@ type WaAuthClientDeps = Readonly<{
         readonly onPairingRefresh?: (forceManual: boolean) => void;
         readonly onPaired?: (credentials: WaAuthCredentials) => void;
         readonly onError?: (error: Error) => void;
+        /** Server forced a passkey (Shortcake) prologue; `hasSigner` = a signer is configured. */
+        readonly onPasskeyRequired?: (hasSigner: boolean) => void;
+        /** External WebAuthn signer – enables handling forced passkey (Shortcake) prologues. */
+        readonly signPasskeyAssertion?: WaShortcakeAssertionSigner;
     };
 }>;
 /**
@@ -42,8 +47,11 @@ export declare class WaAuthClient {
     private readonly isConnected?;
     private readonly qrFlow;
     private readonly pairingFlow;
+    private readonly socket;
+    private readonly shortcakeFlow;
     private credentials;
     private versionOverride;
+    private mobileAppVersionOverride;
     constructor(options: WaAuthClientOptions, deps: WaAuthClientDeps);
     /**
      * Returns a snapshot of auth readiness flags (connection, registration,
@@ -78,6 +86,15 @@ export declare class WaAuthClient {
      * options.
      */
     setNextConnectVersion(version: string): void;
+    /**
+     * 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: string): void;
     /** Clears the in-memory QR and pairing sessions without touching storage. */
     clearTransientState(): Promise<void>;
     /**
@@ -139,6 +156,14 @@ export declare class WaAuthClient {
     handleIncomingIqSet(node: BinaryNode): Promise<boolean>;
     /** Dispatcher: returns `true` when `node` is a link-code companion notification. */
     handleLinkCodeNotification(node: BinaryNode): Promise<boolean>;
+    /**
+     * 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`.
+     */
+    private handleShortcakeNotification;
     /** Dispatcher: returns `true` when `node` is a companion-registration refresh notification. */
     handleCompanionRegRefreshNotification(node: BinaryNode): Promise<boolean>;
     private patchCredentials;

package/dist/auth/WaAuthClient.js

@@ -4,10 +4,12 @@ exports.WaAuthClient = void 0;
 const credentials_flow_1 = require("./credentials-flow");
 const WaPairingFlow_1 = require("./pairing/WaPairingFlow");
 const WaQrFlow_1 = require("./pairing/WaQrFlow");
+const WaShortcakeFlow_1 = require("./pairing/WaShortcakeFlow");
 const constants_1 = require("../protocol/constants");
+const global_1 = require("../transport/node/builders/global");
+const WaClientPayload_1 = require("../transport/noise/WaClientPayload");
 const bytes_1 = require("../util/bytes");
 const primitives_1 = require("../util/primitives");
-const runtime_1 = require("../util/runtime");
 /**
  * Owns the auth/pairing lifecycle and persistence of {@link WaAuthCredentials}.
  * Exposed as `client.auth` on a {@link WaClient}.
@@ -20,12 +22,8 @@ const runtime_1 = require("../util/runtime");
 class WaAuthClient {
     constructor(options, deps) {
         this.versionOverride = null;
-        const deviceBrowser = options.deviceBrowser ?? constants_1.WA_DEFAULTS.DEVICE_BROWSER;
-        const device = Object.freeze({
-            browser: deviceBrowser,
-            osDisplayName: options.deviceOsDisplayName ?? (0, runtime_1.getRuntimeOsDisplayName)(),
-            platform: options.devicePlatform ?? (0, constants_1.getWaCompanionPlatformId)(deviceBrowser)
-        });
+        this.mobileAppVersionOverride = null;
+        const device = (0, constants_1.resolveWaDeviceIdentity)(options);
         this.options = Object.freeze({
             ...options,
             deviceBrowser: device.browser,
@@ -62,6 +60,23 @@ class WaAuthClient {
             },
             dangerous: options.dangerous
         });
+        this.socket = deps.socket;
+        const signAssertion = deps.callbacks?.signPasskeyAssertion;
+        this.shortcakeFlow = signAssertion
+            ? new WaShortcakeFlow_1.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: (0, WaClientPayload_1.resolveDevicePropsPlatformType)(device.browser)
+            })
+            : null;
     }
     /**
      * Returns a snapshot of auth readiness flags (connection, registration,
@@ -107,12 +122,15 @@ 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 (0, credentials_flow_1.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
@@ -128,12 +146,24 @@ 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
@@ -292,9 +322,35 @@ class WaAuthClient {
     }
     /** Dispatcher: returns `true` when `node` is a link-code companion notification. */
     async handleLinkCodeNotification(node) {
+        const type = node.attrs.type;
+        if (type === constants_1.WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST ||
+            type === constants_1.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 === constants_1.WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST) {
+            this.callbacks.onPasskeyRequired?.(this.shortcakeFlow !== null);
+        }
+        if (this.shortcakeFlow) {
+            return this.shortcakeFlow.handleIncomingNotification(node);
+        }
+        if (node.attrs.type === constants_1.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((0, global_1.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/auth/credentials-flow.d.ts

@@ -17,5 +17,13 @@ export declare function persistCredentials(args: WaAuthCredentialsFlowArgs, cred
 export declare function buildCommsConfig(logger: Logger, credentials: WaAuthCredentials, socketOptions: WaAuthSocketOptions, clientOptions: Pick<WaAuthClientOptions, 'deviceBrowser' | 'deviceOsDisplayName' | 'requireFullSync' | 'version' | 'mobileTransport'> & {
     readonly noiseTrustedRootCa?: WaNoiseRootCa;
     readonly disableNoiseCertificateChainVerification?: boolean;
+    /**
+     * One-shot override for the mobile `deviceInfo.appVersion` on this
+     * connect, applied on top of the resolved mobile transport. Used by
+     * the `recoverFromClientTooOld` auto-retry to inject a fresh Android
+     * app version fetched from the public listing. Ignored for web
+     * sessions.
+     */
+    readonly mobileAppVersionOverride?: string;
 }): Promise<WaCommsConfig>;
 export {};

package/dist/auth/credentials-flow.js

@@ -66,6 +66,26 @@ async function resolveVersion(version) {
     }
     return resolved;
 }
+/**
+ * Validates the user-supplied `version` string against the transport it will
+ * feed. A mobile session sends the version as the four-part Android app
+ * version (`2.YY.WW.RR`) in the login payload, so it must have exactly four
+ * numeric parts. A web session advertises up to five parts (`2.3000.x[.y.z]`),
+ * so three to five numeric parts are accepted.
+ */
+function assertValidVersion(version, mobile) {
+    const parts = version.split('.');
+    const allNumeric = parts.every((part) => (0, primitives_1.parseOptionalInt)(part) !== undefined);
+    if (mobile) {
+        if (parts.length !== 4 || !allNumeric) {
+            throw new Error(`mobile session requires a 4-part numeric version (e.g. 2.26.27.70), got: ${version}`);
+        }
+        return;
+    }
+    if (parts.length < 3 || parts.length > 5 || !allNumeric) {
+        throw new Error(`web session requires a 3- to 5-part numeric version (e.g. 2.3000.1040229458), got: ${version}`);
+    }
+}
 async function buildCommsConfig(logger, credentials, socketOptions, clientOptions) {
     const meJid = credentials.meJid;
     const registered = meJid !== null && meJid !== undefined;
@@ -86,6 +106,12 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
                 ? 'credentials'
                 : 'none'
     });
+    const resolvedVersion = effectiveMobileTransport && clientOptions.mobileAppVersionOverride !== undefined
+        ? undefined
+        : await resolveVersion(clientOptions.version);
+    if (resolvedVersion !== undefined) {
+        assertValidVersion(resolvedVersion, Boolean(effectiveMobileTransport));
+    }
     if (effectiveMobileTransport) {
         if (wsProxy) {
             throw new Error('mobileTransport does not support socketOptions.proxy.ws – remove the proxy option or open an issue to add TCP proxy support');
@@ -93,11 +119,18 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
         if (!loginIdentity) {
             throw new Error('mobileTransport requires registered credentials (meJid) – run the mobile bridge flow first');
         }
+        if (clientOptions.mobileAppVersionOverride !== undefined) {
+            assertValidVersion(clientOptions.mobileAppVersionOverride, true);
+        }
+        const appVersionOverride = clientOptions.mobileAppVersionOverride ?? resolvedVersion;
+        const deviceInfo = appVersionOverride
+            ? { ...effectiveMobileTransport.deviceInfo, appVersion: appVersionOverride }
+            : effectiveMobileTransport.deviceInfo;
         const loginPayload = (0, WaMobileClientPayload_1.buildMobileLoginPayload)({
             username: loginIdentity.username,
             device: loginIdentity.device,
             passive: effectiveMobileTransport.passive ?? false,
-            deviceInfo: effectiveMobileTransport.deviceInfo,
+            deviceInfo,
             pushName: effectiveMobileTransport.pushName,
             yearClass: effectiveMobileTransport.yearClass,
             memClass: effectiveMobileTransport.memClass
@@ -122,7 +155,7 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
             }
         };
     }
-    const versionBase = await resolveVersion(clientOptions.version);
+    const versionBase = resolvedVersion;
     return {
         url: socketOptions.url,
         urls: socketOptions.urls,

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

@@ -0,0 +1,93 @@
+import type { WaAuthCredentials } from '../types';
+import type { Logger } from '../../infra/log/types';
+import { proto } from '../../proto';
+import type { BinaryNode } from '../../transport/types';
+/**
+ * Externally-provided WebAuthn assertion. The passkey/credential source lives
+ * OUTSIDE the protocol layer – the caller signs the server's request options
+ * however it likes (real authenticator, virtual authenticator, relay…) and
+ * hands back the raw assertion + credential id.
+ */
+export type WaShortcakeAssertionSigner = (requestOptions: Uint8Array) => Promise<{
+    readonly credentialId: Uint8Array;
+    readonly webauthnAssertion: Uint8Array;
+}>;
+export interface WaShortcakeFlowOptions {
+    readonly logger: Logger;
+    readonly socket: {
+        readonly sendNode: (node: BinaryNode) => Promise<void>;
+        readonly query: (node: BinaryNode, timeoutMs: number) => Promise<BinaryNode>;
+    };
+    /** WebAuthn signer (passkey assertion) – external, keeps credentials out of the protocol. */
+    readonly signAssertion: WaShortcakeAssertionSigner;
+    /**
+     * Companion credentials access. The pairing-request payload (`PairingRequest`:
+     * noise static + identity pubkey + ADV secret) is built internally from
+     * these; the ADV secret is also rotated on a prologue request (matching the
+     * official clients), so an updater is required.
+     */
+    readonly auth: {
+        readonly getCredentials: () => WaAuthCredentials | null;
+        readonly updateCredentials: (credentials: WaAuthCredentials) => Promise<void>;
+    };
+    /** Companion platform reported in the ephemeral identity. */
+    readonly deviceType?: proto.DeviceProps.PlatformType;
+    /** Optional internal observability hooks. */
+    readonly callbacks?: {
+        /** Verification code derived after the primary replies. */
+        readonly emitVerificationCode?: (code: string) => void;
+        /** Prologue accepted by the server; now waiting for the primary. */
+        readonly emitPrologueSent?: () => void;
+    };
+}
+/**
+ * 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 declare class WaShortcakeFlow {
+    private readonly opts;
+    private session;
+    private handoffKey;
+    constructor(options: WaShortcakeFlowOptions);
+    hasSession(): boolean;
+    clearSession(): void;
+    /**
+     * 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.
+     */
+    executePrologue(args?: {
+        readonly requestOptions?: Uint8Array;
+        readonly pairingHandoffProof?: Uint8Array;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    handleIncomingNotification(node: BinaryNode): Promise<boolean>;
+    private handlePasskeyPrologueRequest;
+    /**
+     * 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`.
+     */
+    private stashHandoffKeyAndRotateAdv;
+    private handlePrimaryEphemeralIdentity;
+    /** Current verification code, once derived. */
+    getVerificationCode(): string | null;
+    /**
+     * Confirms the verification code: builds + AES-GCM seals the pairing request
+     * and sends the `encrypted_pairing_request` IQ.
+     */
+    confirmVerificationCode(): Promise<void>;
+    private requestPasskeyRequestOptions;
+    private requestRef;
+    private ackNotification;
+}

package/dist/auth/pairing/WaShortcakeFlow.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaShortcakeFlow = void 0;
+const shortcake_crypto_1 = require("../pairing/shortcake-crypto");
+const _crypto_1 = require("../../crypto");
+const _proto_1 = require("../../proto");
+const constants_1 = require("../../protocol/constants");
+const global_1 = require("../../transport/node/builders/global");
+const shortcake_1 = require("../../transport/node/builders/shortcake");
+const helpers_1 = require("../../transport/node/helpers");
+const query_1 = require("../../transport/node/query");
+const bytes_1 = require("../../util/bytes");
+/** HKDF info for the pairing handoff HMAC key (derived from the ADV secret). */
+const HANDOFF_KEY_INFO = bytes_1.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.
+ */
+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_1.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 (0, shortcake_crypto_1.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 = (0, _crypto_1.hmacSha256Sign)(handoffKey.hmac, companion.prologuePayloadBytes);
+        }
+        const skipHandoffUx = pairingHandoffProof !== undefined;
+        const response = await this.opts.socket.query((0, shortcake_1.buildSetPasskeyPrologueRequestNode)({
+            credentialId: assertion.credentialId,
+            webauthnAssertion: assertion.webauthnAssertion,
+            prologuePayload: companion.prologuePayloadBytes,
+            pairingHandoffProof
+        }), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
+        (0, query_1.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 === constants_1.WA_NOTIFICATION_TYPES.PASSKEY_PROLOGUE_REQUEST) {
+            return this.handlePasskeyPrologueRequest(node);
+        }
+        if (node.attrs.type === constants_1.WA_NOTIFICATION_TYPES.CRSC_CONTINUATION) {
+            return this.handlePrimaryEphemeralIdentity(node);
+        }
+        return false;
+    }
+    async handlePasskeyPrologueRequest(node) {
+        await this.ackNotification(node);
+        await this.stashHandoffKeyAndRotateAdv();
+        const optionsNode = (0, helpers_1.findNodeChild)(node, constants_1.WA_NODE_TAGS.PASSKEY_REQUEST_OPTIONS);
+        const requestOptions = optionsNode
+            ? (0, helpers_1.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: (0, _crypto_1.hkdf)(credentials.advSecretKey, null, HANDOFF_KEY_INFO, 32),
+            ts: Date.now()
+        };
+        await this.opts.auth.updateCredentials({
+            ...credentials,
+            advSecretKey: await (0, _crypto_1.randomBytesAsync)(32)
+        });
+    }
+    async handlePrimaryEphemeralIdentity(node) {
+        const child = (0, helpers_1.findNodeChild)(node, constants_1.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 = (0, shortcake_crypto_1.decodePrimaryEphemeralIdentity)((0, helpers_1.decodeNodeContentUtf8OrBytes)(child.content, 'shortcake.primary_ephemeral_identity'));
+        const nonceResponse = await this.opts.socket.query((0, shortcake_1.buildSetCompanionNonceRequestNode)(session.companion.companionNonce), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
+        (0, query_1.assertIqResult)(nonceResponse, 'shortcake set-companion-nonce');
+        const verificationCode = (0, shortcake_crypto_1.deriveVerificationCode)(session.companion.companionNonce, primary);
+        const encryptionKey = await (0, shortcake_crypto_1.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_1.proto.PairingRequest.encode({
+            companionPublicKey: credentials.noiseKeyPair.pubKey,
+            companionIdentityKey: credentials.registrationInfo.identityKeyPair.pubKey,
+            advSecret: credentials.advSecretKey
+        }).finish();
+        const envelope = await (0, shortcake_crypto_1.encryptPairingRequest)(session.encryptionKey, plaintext);
+        const response = await this.opts.socket.query((0, shortcake_1.buildSetEncryptedPairingRequestRequestNode)(envelope), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
+        (0, query_1.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((0, shortcake_1.buildGetPasskeyRequestOptionsRequestNode)(), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
+        (0, query_1.assertIqResult)(response, 'shortcake get-passkey-request-options');
+        const optionsNode = (0, helpers_1.findNodeChild)(response, constants_1.WA_NODE_TAGS.PASSKEY_REQUEST_OPTIONS);
+        if (!optionsNode) {
+            throw new Error('shortcake: get-passkey-request-options response missing options');
+        }
+        return (0, helpers_1.decodeNodeContentUtf8OrBytes)(optionsNode.content, 'shortcake.passkey_request_options');
+    }
+    async requestRef() {
+        const response = await this.opts.socket.query((0, shortcake_1.buildShortcakeGetRefRequestNode)(), constants_1.WA_DEFAULTS.IQ_TIMEOUT_MS);
+        (0, query_1.assertIqResult)(response, 'shortcake get-ref');
+        const refNode = (0, helpers_1.findNodeChild)(response, constants_1.WA_NODE_TAGS.REF);
+        if (!refNode) {
+            throw new Error('shortcake: get-ref response missing ref');
+        }
+        return bytes_1.TEXT_DECODER.decode((0, helpers_1.decodeNodeContentUtf8OrBytes)(refNode.content, 'shortcake.ref'));
+    }
+    async ackNotification(node) {
+        await this.opts.socket.sendNode((0, global_1.buildAckNode)({ kind: 'notification', node }));
+    }
+}
+exports.WaShortcakeFlow = WaShortcakeFlow;