zapo-js 1.3.0 → 1.5.0

package/dist/auth/pairing/companion-host.d.ts

@@ -0,0 +1,105 @@
+import { type SignalKeyPair } from '../../crypto';
+/**
+ * `@sensitive` `advSecretKey` is companion secret material; consumers must not
+ * persist it without encryption at rest.
+ *
+ * Fields decoded from a companion pairing QR string. The companion (the device
+ * being linked) generates these; the primary consumes them to sign the device
+ * identity. `advSecretKey` is the companion's secret, not the primary's.
+ */
+export interface ParsedCompanionQr {
+    readonly ref: string;
+    readonly noisePublicKey: Uint8Array;
+    readonly identityPublicKey: Uint8Array;
+    readonly advSecretKey: Uint8Array;
+    readonly platform: string;
+}
+/**
+ * Parses a companion pairing QR of the form
+ * `ref,noisePubB64,identityPubB64,advSecretB64,platform`. The `ref` may itself
+ * contain commas, so the four trailing fields are taken from the end.
+ *
+ * @throws when fewer than 5 comma-separated fields are present.
+ */
+export declare function parseCompanionQr(qr: string): ParsedCompanionQr;
+/** `@sensitive` Carries the primary's `accountIdentityKeyPair` private key. */
+export interface BuildSignedKeyIndexListInput {
+    readonly accountIdentityKeyPair: SignalKeyPair;
+    readonly rawId: number;
+    readonly currentIndex: number;
+    readonly timestampSeconds: number;
+    readonly validIndexes: readonly number[];
+}
+/**
+ * Builds the account-signed `ADVSignedKeyIndexList` bytes for the current device
+ * set. The zero-valued `accountType` enum is omitted to match the phone's byte
+ * layout.
+ */
+export declare function buildSignedKeyIndexList(input: BuildSignedKeyIndexListInput): Promise<Uint8Array>;
+/**
+ * `@sensitive` Carries the primary's `accountIdentityKeyPair` private key and the
+ * companion's `advSecretKey`; do not persist unencrypted.
+ */
+export interface BuildSignedCompanionIdentityInput {
+    readonly accountIdentityKeyPair: SignalKeyPair;
+    readonly companionIdentityPublicKey: Uint8Array;
+    readonly advSecretKey: Uint8Array;
+    readonly rawId: number;
+    readonly keyIndex: number;
+    readonly timestampSeconds: number;
+    readonly validIndexes: readonly number[];
+}
+export interface SignedCompanionIdentity {
+    /** `ADVSignedDeviceIdentityHMAC` bytes for the `<device-identity>` node. */
+    readonly deviceIdentityBytes: Uint8Array;
+    /** `ADVSignedKeyIndexList` bytes for the `<key-index-list>` node. */
+    readonly keyIndexListBytes: Uint8Array;
+}
+/**
+ * Builds the signed device identity and key-index list for a linking companion.
+ * The byte layout mirrors WhatsApp's phone (and the in-repo fake-server
+ * reference): the zero-valued `accountType`/`deviceType` enum fields are omitted
+ * so the signed `details` match what the companion verifies.
+ */
+export declare function buildSignedCompanionIdentity(input: BuildSignedCompanionIdentityInput): Promise<SignedCompanionIdentity>;
+/**
+ * Derives the `<pem>` AES-GCM key the phone ships in the pair-device upload:
+ * `HKDF-SHA256(ikm = advSecret, salt = companionNoisePublicKey, info)`. Not yet
+ * verified against a live server from this implementation; see
+ * `CompanionHostOptions.includePem`.
+ */
+export declare function derivePemKey(advSecretKey: Uint8Array, companionNoisePublicKey: Uint8Array): Uint8Array;
+/**
+ * `@sensitive` Holds the `primaryEphemeralKeyPair` private key and the derived
+ * `sharedEphemeral`; keep in memory only, never persist unencrypted.
+ */
+export interface LinkCodePrimaryHello {
+    readonly primaryEphemeralKeyPair: SignalKeyPair;
+    /** `salt(32) || counter(16) || AES-CTR(primaryEphemeralPub)` for `primary_hello`. */
+    readonly wrappedPrimaryEphemeralPub: Uint8Array;
+    /** ECDH(primaryEphemeralPriv, companionEphemeralPub); stashed for the finish step. */
+    readonly sharedEphemeral: Uint8Array;
+}
+/**
+ * Link-code handshake, primary step 1: unwrap the companion ephemeral with the
+ * pairing code, generate the primary ephemeral, compute the shared ECDH secret,
+ * and wrap the primary ephemeral for the `primary_hello` stanza. Mirror of the
+ * companion's `createCompanionHello` + primary-ephemeral unwrap.
+ */
+export declare function preparePrimaryHello(args: {
+    readonly pairingCode: string;
+    readonly wrappedCompanionEphemeralPub: Uint8Array;
+}): Promise<LinkCodePrimaryHello>;
+/**
+ * Link-code handshake, primary step 2: decrypt the `companion_finish` key bundle
+ * and derive the shared `advSecret` (byte-identical to what the companion
+ * derives). Validates that the bundle binds both identities.
+ *
+ * @throws when the bundle's embedded identities do not match.
+ */
+export declare function completePrimaryHandshake(args: {
+    readonly sharedEphemeral: Uint8Array;
+    readonly wrappedKeyBundle: Uint8Array;
+    readonly companionIdentityPub: Uint8Array;
+    readonly primaryIdentityKeyPair: SignalKeyPair;
+}): Promise<Uint8Array>;

package/dist/auth/pairing/companion-host.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCompanionQr = parseCompanionQr;
+exports.buildSignedKeyIndexList = buildSignedKeyIndexList;
+exports.buildSignedCompanionIdentity = buildSignedCompanionIdentity;
+exports.derivePemKey = derivePemKey;
+exports.preparePrimaryHello = preparePrimaryHello;
+exports.completePrimaryHandshake = completePrimaryHandshake;
+const _crypto_1 = require("../../crypto");
+const _proto_1 = require("../../proto");
+const _protocol_1 = require("../../protocol");
+const _signal_1 = require("../../signal");
+const bytes_1 = require("../../util/bytes");
+const PEM_HKDF_INFO = bytes_1.TEXT_ENCODER.encode('Canonical Ent Companion Nonce Encrypt');
+const PBKDF2_ITERATIONS = 131072;
+const PAIRING_AES_KEY_BYTES = 32;
+/**
+ * Parses a companion pairing QR of the form
+ * `ref,noisePubB64,identityPubB64,advSecretB64,platform`. The `ref` may itself
+ * contain commas, so the four trailing fields are taken from the end.
+ *
+ * @throws when fewer than 5 comma-separated fields are present.
+ */
+function parseCompanionQr(qr) {
+    const parts = qr.split(',');
+    if (parts.length < 5) {
+        throw new Error(`companion qr must have at least 5 comma-separated parts, got ${parts.length}`);
+    }
+    const platform = parts[parts.length - 1];
+    const advSecretB64 = parts[parts.length - 2];
+    const identityPubB64 = parts[parts.length - 3];
+    const noisePubB64 = parts[parts.length - 4];
+    const ref = parts.slice(0, parts.length - 4).join(',');
+    return {
+        ref,
+        noisePublicKey: (0, bytes_1.decodeBase64Url)(noisePubB64, 'companionQr.noisePublicKey'),
+        identityPublicKey: (0, bytes_1.decodeBase64Url)(identityPubB64, 'companionQr.identityPublicKey'),
+        advSecretKey: (0, bytes_1.decodeBase64Url)(advSecretB64, 'companionQr.advSecretKey'),
+        platform
+    };
+}
+/**
+ * Builds the account-signed `ADVSignedKeyIndexList` bytes for the current device
+ * set. The zero-valued `accountType` enum is omitted to match the phone's byte
+ * layout.
+ */
+async function buildSignedKeyIndexList(input) {
+    const details = _proto_1.proto.ADVKeyIndexList.encode({
+        rawId: input.rawId,
+        timestamp: input.timestampSeconds,
+        currentIndex: input.currentIndex,
+        validIndexes: [...input.validIndexes]
+    }).finish();
+    const accountSignature = await (0, _signal_1.signKeyIndexList)(details, input.accountIdentityKeyPair);
+    return _proto_1.proto.ADVSignedKeyIndexList.encode({ details, accountSignature }).finish();
+}
+/**
+ * Builds the signed device identity and key-index list for a linking companion.
+ * The byte layout mirrors WhatsApp's phone (and the in-repo fake-server
+ * reference): the zero-valued `accountType`/`deviceType` enum fields are omitted
+ * so the signed `details` match what the companion verifies.
+ */
+async function buildSignedCompanionIdentity(input) {
+    const accountSignatureKey = (0, _crypto_1.toRawPubKey)(input.accountIdentityKeyPair.pubKey);
+    const details = _proto_1.proto.ADVDeviceIdentity.encode({
+        rawId: input.rawId,
+        timestamp: input.timestampSeconds,
+        keyIndex: input.keyIndex
+    }).finish();
+    const accountSignature = await (0, _signal_1.generateDeviceIdentityAccountSignature)(details, input.companionIdentityPublicKey, input.accountIdentityKeyPair);
+    const signedIdentity = _proto_1.proto.ADVSignedDeviceIdentity.encode({
+        details,
+        accountSignatureKey,
+        accountSignature
+    }).finish();
+    const hmac = (0, _signal_1.computeAdvIdentityHmac)(input.advSecretKey, signedIdentity);
+    const deviceIdentityBytes = _proto_1.proto.ADVSignedDeviceIdentityHMAC.encode({
+        details: signedIdentity,
+        hmac
+    }).finish();
+    const keyIndexListBytes = await buildSignedKeyIndexList({
+        accountIdentityKeyPair: input.accountIdentityKeyPair,
+        rawId: input.rawId,
+        currentIndex: input.keyIndex,
+        timestampSeconds: input.timestampSeconds,
+        validIndexes: input.validIndexes
+    });
+    return { deviceIdentityBytes, keyIndexListBytes };
+}
+/**
+ * Derives the `<pem>` AES-GCM key the phone ships in the pair-device upload:
+ * `HKDF-SHA256(ikm = advSecret, salt = companionNoisePublicKey, info)`. Not yet
+ * verified against a live server from this implementation; see
+ * `CompanionHostOptions.includePem`.
+ */
+function derivePemKey(advSecretKey, companionNoisePublicKey) {
+    return (0, _crypto_1.hkdf)(advSecretKey, companionNoisePublicKey, PEM_HKDF_INFO, 32);
+}
+/**
+ * Link-code handshake, primary step 1: unwrap the companion ephemeral with the
+ * pairing code, generate the primary ephemeral, compute the shared ECDH secret,
+ * and wrap the primary ephemeral for the `primary_hello` stanza. Mirror of the
+ * companion's `createCompanionHello` + primary-ephemeral unwrap.
+ */
+async function preparePrimaryHello(args) {
+    if (args.wrappedCompanionEphemeralPub.length < 48) {
+        throw new Error(`wrapped companion ephemeral pub too short: ${args.wrappedCompanionEphemeralPub.length} bytes (need >= 48)`);
+    }
+    const codeBytes = bytes_1.TEXT_ENCODER.encode(args.pairingCode);
+    const companionCipherKey = await (0, _crypto_1.pbkdf2Sha256)(codeBytes, args.wrappedCompanionEphemeralPub.subarray(0, 32), PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
+    const companionEphemeralPub = (0, _crypto_1.aesCtrDecrypt)(companionCipherKey, args.wrappedCompanionEphemeralPub.subarray(32, 48), args.wrappedCompanionEphemeralPub.subarray(48));
+    const [primaryEphemeralKeyPair, salt, counter] = await Promise.all([
+        _crypto_1.X25519.generateKeyPair(),
+        (0, _crypto_1.randomBytesAsync)(32),
+        (0, _crypto_1.randomBytesAsync)(16)
+    ]);
+    const primaryCipherKey = await (0, _crypto_1.pbkdf2Sha256)(codeBytes, salt, PBKDF2_ITERATIONS, PAIRING_AES_KEY_BYTES);
+    const encrypted = (0, _crypto_1.aesCtrEncrypt)(primaryCipherKey, counter, primaryEphemeralKeyPair.pubKey);
+    const sharedEphemeral = await _crypto_1.X25519.scalarMult(primaryEphemeralKeyPair.privKey, companionEphemeralPub);
+    return {
+        primaryEphemeralKeyPair,
+        wrappedPrimaryEphemeralPub: (0, bytes_1.concatBytes)([salt, counter, encrypted]),
+        sharedEphemeral
+    };
+}
+/**
+ * Link-code handshake, primary step 2: decrypt the `companion_finish` key bundle
+ * and derive the shared `advSecret` (byte-identical to what the companion
+ * derives). Validates that the bundle binds both identities.
+ *
+ * @throws when the bundle's embedded identities do not match.
+ */
+async function completePrimaryHandshake(args) {
+    const bundleEncryptionKey = (0, _crypto_1.hkdf)(args.sharedEphemeral, args.wrappedKeyBundle.subarray(0, 32), _protocol_1.WA_PAIRING_KDF_INFO.LINK_CODE_BUNDLE, 32);
+    const plaintextBundle = (0, _crypto_1.aesGcmDecrypt)(bundleEncryptionKey, args.wrappedKeyBundle.subarray(32, 44), args.wrappedKeyBundle.subarray(44));
+    const bundleCompanionIdentity = plaintextBundle.subarray(0, 32);
+    const bundlePrimaryIdentity = plaintextBundle.subarray(32, 64);
+    const bundleSecret = plaintextBundle.subarray(64);
+    const rawCompanionIdentity = (0, _crypto_1.toRawPubKey)(args.companionIdentityPub);
+    if (!(0, bytes_1.uint8Equal)(bundlePrimaryIdentity, (0, _crypto_1.toRawPubKey)(args.primaryIdentityKeyPair.pubKey))) {
+        throw new Error('link-code bundle primary identity mismatch');
+    }
+    if (!(0, bytes_1.uint8Equal)(bundleCompanionIdentity, rawCompanionIdentity)) {
+        throw new Error('link-code bundle companion identity mismatch');
+    }
+    const sharedIdentity = await _crypto_1.X25519.scalarMult(args.primaryIdentityKeyPair.privKey, rawCompanionIdentity);
+    return (0, _crypto_1.hkdf)((0, bytes_1.concatBytes)([args.sharedEphemeral, sharedIdentity, bundleSecret]), null, _protocol_1.WA_PAIRING_KDF_INFO.ADV_SECRET, 32);
+}

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();
+}

package/dist/auth/types.d.ts

@@ -39,10 +39,11 @@ export type WaAuthSocketOptions = Pick<WaCommsConfig, 'url' | 'urls' | 'protocol
     };
 };
 /**
- * WhatsApp Web version supplied to {@link WaAuthClientOptions.version}. Either
- * a literal `'x.y.z'` string or an async resolver invoked once per connect,
- * letting callers refresh the version (e.g. via `fetchLatestWaWebVersion`)
- * without rebuilding the client.
+ * Version supplied to {@link WaAuthClientOptions.version}. Either a literal
+ * dotted-numeric string or an async resolver invoked once per connect,
+ * letting callers refresh the version (e.g. via `fetchLatestWaWebVersion` or
+ * `fetchLatestWaMobileVersion`) without rebuilding the client. See
+ * {@link WaAuthClientOptions.version} for the per-transport part-count rules.
  */
 export type WaVersionResolver = string | (() => string | Promise<string>);
 export interface WaAuthClientOptions {
@@ -70,11 +71,21 @@ export interface WaAuthClientOptions {
      */
     readonly requireFullSync?: boolean;
     /**
-     * WhatsApp Web version the client advertises. Either a `'x.y.z'` literal
-     * or a (sync/async) resolver invoked once per connect – use the resolver
-     * form together with {@link fetchLatestWaWebVersion} to refresh the
-     * version when the hardcoded default starts hitting `failure_client_too_old`.
-     * Defaults to a tested production version.
+     * Version the client advertises. Either a dotted-numeric literal or a
+     * (sync/async) resolver invoked once per connect – use the resolver form
+     * together with {@link fetchLatestWaWebVersion} /
+     * {@link fetchLatestWaMobileVersion} to refresh the version when the
+     * hardcoded default starts hitting `failure_client_too_old`.
+     *
+     * The accepted shape depends on the transport resolved for the connect:
+     * - **Web** sessions take a 3- to 5-part version (`2.3000.x[.y.z]`); all
+     *   supplied parts are advertised in the noise payload.
+     * - **Mobile** sessions take exactly a 4-part Android app version
+     *   (`2.26.27.70`); it overrides `mobileTransport.deviceInfo.appVersion`
+     *   in the login payload.
+     *
+     * An invalid part count for the resolved transport throws on connect.
+     * Defaults to a tested production version per transport.
      */
     readonly version?: WaVersionResolver;
     /**

package/dist/client/WaClient.d.ts

@@ -8,6 +8,7 @@ import type { WaEmailCoordinator } from './coordinators/WaEmailCoordinator';
 import type { WaGroupCoordinator } from './coordinators/WaGroupCoordinator';
 import type { WaLowLevelCoordinator } from './coordinators/WaLowLevelCoordinator';
 import type { WaMessageCoordinator } from './coordinators/WaMessageCoordinator';
+import type { WaMobileCoordinator } from './coordinators/WaMobileCoordinator';
 import type { WaNewsletterCoordinator } from './coordinators/WaNewsletterCoordinator';
 import type { WaPresenceCoordinator } from './coordinators/WaPresenceCoordinator';
 import type { WaPrivacyCoordinator } from './coordinators/WaPrivacyCoordinator';
@@ -31,11 +32,13 @@ declare class WaClientImpl extends EventEmitter {
     private activeIncomingHandlers;
     private readonly incomingHandlersDrainedWaiters;
     private disposePlugins;
+    private readonly pluginInstallInput;
     /**
      * @param options Client configuration (store, transport, addons, history...).
      * @param logger  Optional structured logger. Defaults to a `ConsoleLogger('info')`.
      */
     constructor(options: WaClientOptions, logger?: Logger);
+    private installPlugins;
     private runClientTooOldRecover;
     /** Strongly-typed `EventEmitter#on` over {@link WaClientEventMap}. */
     on<K extends keyof WaClientEventMap>(event: K, listener: WaClientEventMap[K]): this;
@@ -100,11 +103,12 @@ declare class WaClientImpl extends EventEmitter {
     connect(): Promise<void>;
     /**
      * Closes the transport gracefully: pauses incoming events, flushes the
-     * write-behind persistence queue, and emits a `connection` close event
-     * with reason `client_disconnected`. Does not clear stored credentials -
-     * call {@link connect} again to resume the same session. There is no
-     * built-in auto-reconnect; subscribe to `connection: { status: 'close' }`
-     * and decide your own backoff.
+     * write-behind persistence queue, disposes installed plugins, and emits a
+     * `connection` close event with reason `client_disconnected`. Does not
+     * clear stored credentials - call {@link connect} again to resume the same
+     * session, which reinstalls the plugins. There is no built-in
+     * auto-reconnect; subscribe to `connection: { status: 'close' }` and decide
+     * your own backoff.
      */
     disconnect(): Promise<void>;
     /**
@@ -166,6 +170,12 @@ declare class WaClientImpl extends EventEmitter {
      * via `options.mobileTransport`. See {@link WaEmailCoordinator}.
      */
     get email(): WaEmailCoordinator;
+    /**
+     * Mobile coordinator: host and manage companion devices linked to this
+     * mobile-primary account (link via QR or pairing code, list, revoke).
+     * Requires a registered primary session. See {@link WaMobileCoordinator}.
+     */
+    get mobile(): WaMobileCoordinator;
     /**
      * Unpairs this companion device by removing it server-side. Requires an
      * authenticated session; throws when no `meJid` is present.