zapo-js 1.2.1 → 1.4.0

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,6 +47,8 @@ export declare class WaAuthClient {
     private readonly isConnected?;
     private readonly qrFlow;
     private readonly pairingFlow;
+    private readonly socket;
+    private readonly shortcakeFlow;
     private credentials;
     private versionOverride;
     constructor(options: WaAuthClientOptions, deps: WaAuthClientDeps);
@@ -139,6 +146,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,7 +4,10 @@ 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");
@@ -62,6 +65,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)(deviceBrowser)
+            })
+            : null;
     }
     /**
      * Returns a snapshot of auth readiness flags (connection, registration,
@@ -134,6 +154,7 @@ 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
@@ -292,9 +313,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/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;

package/dist/auth/pairing/pairing-code-crypto.d.ts

@@ -1,5 +1,6 @@
 import type { SignalKeyPair } from '../../crypto/curves/types';
 export declare const PBKDF2_ITERATIONS: number;
+export declare function encodeBytesToCrockford(bytes: Uint8Array): string;
 export declare function normalizeCustomPairingCode(input: string): string;
 export declare function createCompanionHello(options?: {
     readonly customCode?: string;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PBKDF2_ITERATIONS = void 0;
+exports.encodeBytesToCrockford = encodeBytesToCrockford;
 exports.normalizeCustomPairingCode = normalizeCustomPairingCode;
 exports.createCompanionHello = createCompanionHello;
 exports.completeCompanionFinish = completeCompanionFinish;
@@ -11,7 +12,7 @@ const bytes_1 = require("../../util/bytes");
 const CROCKFORD_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTVWXYZ';
 exports.PBKDF2_ITERATIONS = 2 << 16;
 const PAIRING_AES_KEY_BYTES = 32;
-function bytesToCrockford(bytes) {
+function encodeBytesToCrockford(bytes) {
     let bitCount = 0;
     let value = 0;
     let out = '';
@@ -48,7 +49,7 @@ async function createCompanionHello(options = {}) {
         (0, _crypto_1.randomBytesAsync)(16),
         normalizedCustomCode !== null ? Promise.resolve(null) : (0, _crypto_1.randomBytesAsync)(5)
     ]);
-    const pairingCode = normalizedCustomCode ?? bytesToCrockford(codeBytes);
+    const pairingCode = normalizedCustomCode ?? encodeBytesToCrockford(codeBytes);
     const cipherKey = await (0, _crypto_1.pbkdf2Sha256)(bytes_1.TEXT_ENCODER.encode(pairingCode), salt, exports.PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
     const encrypted = (0, _crypto_1.aesCtrEncrypt)(cipherKey, counter, companionEphemeralKeyPair.pubKey);
     return {

package/dist/auth/pairing/shortcake-crypto.d.ts

@@ -0,0 +1,59 @@
+import type { SignalKeyPair } from '../../crypto/curves/types';
+import { proto } from '../../proto';
+/**
+ * Decoded `PrimaryEphemeralIdentity` the primary device returns: its ephemeral
+ * X25519 public key (32B) and a 32B nonce used to derive the verification code.
+ */
+export interface ShortcakePrimaryEphemeralIdentity {
+    readonly publicKey: Uint8Array;
+    readonly nonce: Uint8Array;
+}
+/**
+ * @sensitive Carries the companion's ephemeral X25519 private key
+ * (`keyPair.privKey`) and the pre-image `companionNonce`. Hold these in memory
+ * for the handshake only; never log or `JSON.stringify` an instance.
+ */
+export interface ShortcakeCompanionEphemeralIdentity {
+    /** Companion ephemeral X25519 keypair (private half kept for the ECDH). */
+    readonly keyPair: SignalKeyPair;
+    /** 32 random bytes committed up-front, revealed only after the primary replies. */
+    readonly companionNonce: Uint8Array;
+    /** Encoded `CompanionEphemeralIdentity` proto (committed + sent in the prologue). */
+    readonly companionEphemeralIdentityBytes: Uint8Array;
+    /** `SHA-256(companionEphemeralIdentity ‖ companionNonce)` – the commitment hash. */
+    readonly commitmentHash: Uint8Array;
+    /** Encoded `ProloguePayload` proto ready for the `SetPasskeyPrologue` IQ. */
+    readonly prologuePayloadBytes: Uint8Array;
+}
+/**
+ * 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 declare function generateCompanionEphemeralIdentity(args: {
+    readonly ref: string;
+    readonly deviceType: proto.DeviceProps.PlatformType;
+}): Promise<ShortcakeCompanionEphemeralIdentity>;
+/** Parses + validates a `PrimaryEphemeralIdentity` proto from the primary. */
+export declare function decodePrimaryEphemeralIdentity(bytes: Uint8Array): ShortcakePrimaryEphemeralIdentity;
+/**
+ * Derives the short verification code shown on both devices:
+ * `Crockford32( primaryNonce[0..5] XOR SHA-256(companionNonce ‖ primaryPubKey)[0..5] )`.
+ */
+export declare function deriveVerificationCode(companionNonce: Uint8Array, primary: ShortcakePrimaryEphemeralIdentity): string;
+/**
+ * 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 declare function deriveEncryptionKey(args: {
+    readonly companionPrivKey: Uint8Array;
+    readonly primaryPublicKey: Uint8Array;
+    readonly deviceType: proto.DeviceProps.PlatformType;
+    readonly ref: string;
+}): Promise<Uint8Array>;
+/**
+ * Encrypts the pairing request plaintext under the derived key and returns the
+ * encoded `EncryptedPairingRequest` proto (random 12-byte IV).
+ */
+export declare function encryptPairingRequest(encryptionKey: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;

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

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCompanionEphemeralIdentity = generateCompanionEphemeralIdentity;
+exports.decodePrimaryEphemeralIdentity = decodePrimaryEphemeralIdentity;
+exports.deriveVerificationCode = deriveVerificationCode;
+exports.deriveEncryptionKey = deriveEncryptionKey;
+exports.encryptPairingRequest = encryptPairingRequest;
+const pairing_code_crypto_1 = require("../pairing/pairing-code-crypto");
+const _crypto_1 = require("../../crypto");
+const X25519_1 = require("../../crypto/curves/X25519");
+const _proto_1 = require("../../proto");
+const bytes_1 = require("../../util/bytes");
+/**
+ * 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 = bytes_1.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.
+ */
+async function generateCompanionEphemeralIdentity(args) {
+    const [keyPair, companionNonce] = await Promise.all([
+        X25519_1.X25519.generateKeyPair(),
+        (0, _crypto_1.randomBytesAsync)(NONCE_BYTES)
+    ]);
+    const companionEphemeralIdentityBytes = _proto_1.proto.CompanionEphemeralIdentity.encode({
+        publicKey: keyPair.pubKey,
+        deviceType: args.deviceType,
+        ref: args.ref
+    }).finish();
+    const commitmentHash = (0, _crypto_1.sha256)((0, bytes_1.concatBytes)([companionEphemeralIdentityBytes, companionNonce]));
+    const prologuePayloadBytes = _proto_1.proto.ProloguePayload.encode({
+        companionEphemeralIdentity: companionEphemeralIdentityBytes,
+        commitment: { hash: commitmentHash }
+    }).finish();
+    return {
+        keyPair,
+        companionNonce,
+        companionEphemeralIdentityBytes,
+        commitmentHash,
+        prologuePayloadBytes
+    };
+}
+/** Parses + validates a `PrimaryEphemeralIdentity` proto from the primary. */
+function decodePrimaryEphemeralIdentity(bytes) {
+    const decoded = _proto_1.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] )`.
+ */
+function deriveVerificationCode(companionNonce, primary) {
+    const digest = (0, _crypto_1.sha256)((0, bytes_1.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 (0, pairing_code_crypto_1.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" )`.
+ */
+async function deriveEncryptionKey(args) {
+    const shared = await X25519_1.X25519.scalarMult(args.companionPrivKey, args.primaryPublicKey);
+    const salt = bytes_1.TEXT_ENCODER.encode(`Companion Pairing ${String(args.deviceType)} with ref ${args.ref}`);
+    return (0, _crypto_1.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).
+ */
+async function encryptPairingRequest(encryptionKey, plaintext) {
+    if (encryptionKey.length !== ENCRYPTION_KEY_BYTES) {
+        throw new Error('shortcake: encryption key must be 32 bytes');
+    }
+    const iv = await (0, _crypto_1.randomBytesAsync)(GCM_IV_BYTES);
+    const encryptedPayload = (0, _crypto_1.aesGcmEncrypt)(encryptionKey, iv, plaintext);
+    return _proto_1.proto.EncryptedPairingRequest.encode({ encryptedPayload, iv }).finish();
+}