zapo-js 0.2.0 → 1.0.0

package/dist/types/appstate/{WaAppStateCrypto.d.ts → crypto/WaAppStateCrypto.d.ts}

@@ -1,10 +1,10 @@
-import type { Proto } from '..';
+import { type Proto } from '../..';
 interface WaAppStateDerivedKeys {
-    readonly indexKey: Uint8Array;
-    readonly valueEncryptionKey: Uint8Array;
-    readonly valueMacKey: Uint8Array;
-    readonly snapshotMacKey: Uint8Array;
-    readonly patchMacKey: Uint8Array;
+    readonly indexHmacKey: Uint8Array;
+    readonly valueEncryptionAesKey: Uint8Array;
+    readonly valueMacHmacKey: Uint8Array;
+    readonly snapshotMacHmacKey: Uint8Array;
+    readonly patchMacHmacKey: Uint8Array;
 }
 interface WaAppStateEncryptedMutation {
     readonly indexMac: Uint8Array;
@@ -18,13 +18,27 @@ interface WaAppStateDecryptedMutation {
     readonly indexMac: Uint8Array;
     readonly valueMac: Uint8Array;
 }
+/**
+ * Implements the app-state mutation cryptography: HKDF key derivation (with
+ * a bounded LRU cache), per-mutation encrypt/decrypt, snapshot/patch MAC
+ * generation, and the LT-hash arithmetic used to track collection state.
+ */
 export declare class WaAppStateCrypto {
     private readonly derivedKeysCache;
     private readonly derivedKeysCacheMaxSize;
-    constructor(derivedKeysCacheMaxSize?: number);
+    private readonly skipMacVerification;
+    constructor(derivedKeysCacheMaxSize?: number, skipMacVerification?: boolean);
+    get isMacVerificationSkipped(): boolean;
+    /** Empties the derived-keys LRU cache (e.g. after a session reset). */
     clearCache(): void;
-    deriveKeys(keyData: Uint8Array): Promise<WaAppStateDerivedKeys>;
-    generateIndexMac(indexKey: Uint8Array, indexBytes: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Derives the index/value/snapshot/patch keys from an app-state sync key.
+     * Cached by base64 of `keyData` (LRU-bounded).
+     */
+    deriveKeys(keyData: Uint8Array): WaAppStateDerivedKeys;
+    /** Computes the HMAC-SHA-256 index MAC over `indexBytes`. */
+    generateIndexMac(indexHmacKey: Uint8Array, indexBytes: Uint8Array): Uint8Array;
+    /** Encrypts a single mutation value with AES-CBC + HMAC value-MAC. */
     encryptMutation(args: {
         readonly operation: number;
         readonly keyId: Uint8Array;
@@ -34,6 +48,7 @@ export declare class WaAppStateCrypto {
         readonly version: number;
         readonly iv?: Uint8Array;
     }): Promise<WaAppStateEncryptedMutation>;
+    /** Verifies and decrypts a single app-state mutation. */
     decryptMutation(args: {
         readonly operation: number;
         readonly keyId: Uint8Array;
@@ -41,10 +56,15 @@ export declare class WaAppStateCrypto {
         readonly indexMac: Uint8Array;
         readonly valueBlob: Uint8Array;
     }): Promise<WaAppStateDecryptedMutation>;
+    /** Generates the HMAC-SHA-512 snapshot MAC over the LT-hash + version + collection name. */
     generateSnapshotMac(keyData: Uint8Array, ltHash: Uint8Array, version: number, collectionName: string): Promise<Uint8Array>;
+    /** Generates the HMAC-SHA-512 patch MAC binding mutations to a collection version. */
     generatePatchMac(keyData: Uint8Array, snapshotMac: Uint8Array, valueMacs: readonly Uint8Array[], version: number, collectionName: string): Promise<Uint8Array>;
+    /** Adds value MACs into the running LT-hash digest for a collection. */
     ltHashAdd(base: Uint8Array, addValues: readonly Uint8Array[]): Promise<Uint8Array>;
+    /** Removes value MACs from the running LT-hash digest (for `remove` operations). */
     ltHashSubtract(base: Uint8Array, removeValues: readonly Uint8Array[]): Promise<Uint8Array>;
+    /** Combined subtract+add LT-hash update used when a key's value MAC changes in place. */
     ltHashSubtractThenAdd(base: Uint8Array, addValues: readonly Uint8Array[], removeValues: readonly Uint8Array[]): Promise<{
         readonly hash: Uint8Array;
         readonly subtractResult: Uint8Array;

package/dist/types/appstate/index.d.ts

@@ -1,7 +1,7 @@
-export * from './constants';
+export { APP_STATE_EMPTY_LT_HASH } from './constants';
 export type { AppStateCollectionName, WaAppStateStoreData, WaAppStateSyncKey, WaAppStateSyncOptions } from './types';
-export { encodeAppStateFingerprint, decodeAppStateFingerprint, decodeAppStateCollections, decodeAppStateSyncKeys } from './encoding';
+export { encodeAppStateFingerprint, decodeAppStateFingerprint, decodeAppStateCollections, decodeAppStateSyncKeys } from './parsers/encoding';
 export * from './utils';
-export { WaAppStateCrypto } from './WaAppStateCrypto';
-export { parseSyncResponse } from './WaAppStateSyncResponseParser';
-export { WaAppStateSyncClient } from './WaAppStateSyncClient';
+export { WaAppStateCrypto } from './crypto/WaAppStateCrypto';
+export { parseSyncResponse } from './parsers/response-parser';
+export { WaAppStateSyncClient } from './sync/WaAppStateSyncClient';

package/dist/types/appstate/{encoding.d.ts → parsers/encoding.d.ts}

@@ -1,7 +1,14 @@
-import type { WaAppStateStoreData, WaAppStateSyncKey } from './types';
+import type { WaAppStateStoreData, WaAppStateSyncKey } from '../types';
 type StoreRow = Readonly<Record<string, unknown>>;
+/** Serializes an app-state sync key fingerprint to its protobuf bytes, or `null` when absent. */
 export declare function encodeAppStateFingerprint(fingerprint: WaAppStateSyncKey['fingerprint']): Uint8Array | null;
+/** Inverse of {@link encodeAppStateFingerprint}; throws on malformed input. */
 export declare function decodeAppStateFingerprint(raw: unknown): WaAppStateSyncKey['fingerprint'] | undefined;
+/** Decodes app-state sync-key SQL rows into {@link WaAppStateSyncKey} records. */
 export declare function decodeAppStateSyncKeys(rows: readonly StoreRow[]): readonly WaAppStateSyncKey[];
+/**
+ * Joins app-state collection-version and index-value SQL rows into the
+ * `collections` shape used by the in-memory app-state store.
+ */
 export declare function decodeAppStateCollections(versionRows: readonly StoreRow[], valueRows: readonly StoreRow[]): WaAppStateStoreData['collections'];
 export {};

package/dist/types/appstate/{WaAppStateSyncResponseParser.d.ts → parsers/response-parser.d.ts}

@@ -1,6 +1,6 @@
-import type { AppStateCollectionName, AppStateCollectionState } from './types';
-import type { Proto } from '..';
-import type { BinaryNode } from '../transport/types';
+import type { AppStateCollectionName, AppStateCollectionState } from '../types';
+import { type Proto } from '../..';
+import type { BinaryNode } from '../../transport/types';
 export interface CollectionResponsePayload {
     readonly collection: AppStateCollectionName;
     readonly state: AppStateCollectionState;
@@ -8,5 +8,15 @@ export interface CollectionResponsePayload {
     readonly patches: readonly Proto.ISyncdPatch[];
     readonly snapshotReference?: Proto.IExternalBlobReference;
 }
+/**
+ * Parses an app-state `sync` IQ response into one payload per collection,
+ * decoding embedded patches and snapshot references. Throws when the IQ is
+ * an error envelope or missing the `<sync>` child.
+ */
 export declare function parseSyncResponse(iqNode: BinaryNode): readonly CollectionResponsePayload[];
+/**
+ * Reads a `<collection>` node and returns the right
+ * {@link AppStateCollectionState} (success / has-more / conflict / fatal /
+ * retryable) based on its `type` attribute and embedded error code.
+ */
 export declare function parseCollectionState(node: BinaryNode): AppStateCollectionState;

package/dist/types/appstate/sync/WaAppStateSyncClient.d.ts

@@ -0,0 +1,105 @@
+import type { WaAppStateMissingKeysEvent, WaAppStateSyncKey, WaAppStateSyncOptions, WaAppStateSyncResult } from '../types';
+import type { Logger } from '../../infra/log/types';
+import { type Proto } from '../..';
+import type { WaAppStateStore } from '../../store/contracts/appstate.store';
+import type { BinaryNode } from '../../transport/types';
+import type { ServerClock } from '../../util/clock';
+/**
+ * Minimal message-key context for incoming app-state key protocol messages.
+ * Uses the proto `Proto.IMessageKey` attribute names so callers can pass an
+ * incoming message's `key` verbatim (no field remapping).
+ */
+interface IncomingKeyEventContext {
+    readonly remoteJid?: string;
+    readonly id?: string;
+    readonly participant?: string;
+    readonly senderDevice: number;
+}
+interface WaAppStateSyncClientOptions {
+    readonly logger: Logger;
+    readonly query: (node: BinaryNode, timeoutMs: number) => Promise<BinaryNode>;
+    readonly store: WaAppStateStore;
+    readonly serverClock: ServerClock;
+    readonly getCurrentMeJid?: () => string | null | undefined;
+    readonly hostDomain?: string;
+    readonly defaultTimeoutMs?: number;
+    readonly onMissingKeys?: (event: WaAppStateMissingKeysEvent) => Promise<void>;
+    readonly skipMacVerification?: boolean;
+    readonly mobilePrimary?: boolean;
+    readonly isOwnAccountDevice?: (deviceJid: string) => boolean;
+    readonly sendKeyShare?: (toDeviceJid: string, keys: readonly WaAppStateSyncKey[], missingKeyIds: readonly Uint8Array[]) => Promise<void>;
+    readonly triggerSync?: () => Promise<void>;
+}
+/**
+ * App-state synchronization client. Owns the sync key inventory, processes
+ * snapshots/patches, encrypts pending mutations, and persists the resulting
+ * collection state in the {@link WaAppStateStore}.
+ */
+export declare class WaAppStateSyncClient {
+    private readonly logger;
+    private readonly query;
+    private readonly store;
+    private readonly serverClock;
+    private readonly getCurrentMeJid?;
+    private readonly hostDomain;
+    private readonly defaultTimeoutMs;
+    private readonly onMissingKeys?;
+    private readonly isOwnAccountDevice?;
+    private readonly sendKeyShare?;
+    private readonly triggerSync?;
+    private readonly crypto;
+    private readonly mobilePrimary;
+    private syncContext;
+    private syncPromise;
+    constructor(options: WaAppStateSyncClientOptions);
+    /**
+     * Returns the active app-state sync key, generating and persisting a new
+     * one when the store is empty (used during initial setup).
+     */
+    ensureInitialSyncKey(): Promise<WaAppStateSyncKey>;
+    /** Imports peer-shared sync keys into the store; returns the count actually added. */
+    importSyncKeys(keys: readonly WaAppStateSyncKey[]): Promise<number>;
+    /** Handler for `AppStateSyncKeyShare` protocol messages – stores received keys and triggers a sync. */
+    handleIncomingKeyShare(context: IncomingKeyEventContext, protocolMessage: Proto.Message.IProtocolMessage): Promise<void>;
+    /** Handler for `AppStateSyncKeyRequest` protocol messages – replies with the requested keys via `sendKeyShare`. */
+    handleIncomingKeyRequest(context: IncomingKeyEventContext, protocolMessage: Proto.Message.IProtocolMessage): Promise<void>;
+    private extractKeyRequestIds;
+    /** Imports the keys from a decoded `AppStateSyncKeyShare` proto message. */
+    importSyncKeyShare(share: Proto.Message.IAppStateSyncKeyShare): Promise<number>;
+    /**
+     * Runs one app-state sync round across the requested collections,
+     * applying any `pendingMutations` and downloading external snapshots
+     * via `options.downloadExternalBlob` when present. Concurrent calls
+     * share the in-flight promise.
+     */
+    sync(options?: WaAppStateSyncOptions): Promise<WaAppStateSyncResult>;
+    private syncOnce;
+    private syncCollectionsRound;
+    private buildCollectionSyncRequest;
+    private buildSyncIqNode;
+    private fetchSyncPayloadByCollection;
+    private processCollectionRound;
+    private createCollectionOutcome;
+    private notifyMissingKeys;
+    private resolveReadyPatches;
+    private validateSnapshot;
+    private parseCollectionPatchVersion;
+    private validatePatch;
+    private applySnapshot;
+    private applyPatch;
+    private decryptSnapshotRecords;
+    private decryptPatchMutations;
+    private assertPatchMacsMatch;
+    private buildOutgoingPatch;
+    private resolveDeviceIndex;
+    private computeNextCollectionState;
+    private normalizeProtoLong;
+    private groupPendingMutations;
+    private preloadKeyData;
+    private getKeyData;
+    private getCollectionState;
+    private setCollectionState;
+    private persistCollectionUpdates;
+    private requireSyncContext;
+}
+export {};

package/dist/types/appstate/types.d.ts

@@ -1,5 +1,5 @@
 import type { Proto } from '..';
-import type { WA_APP_STATE_COLLECTIONS, WA_APP_STATE_COLLECTION_STATES } from '../protocol/constants';
+import type { WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_COLLECTIONS } from '../protocol/constants';
 export type AppStateCollectionName = (typeof WA_APP_STATE_COLLECTIONS)[keyof typeof WA_APP_STATE_COLLECTIONS];
 export type AppStateCollectionState = (typeof WA_APP_STATE_COLLECTION_STATES)[keyof typeof WA_APP_STATE_COLLECTION_STATES];
 export interface WaAppStateSyncKey {

package/dist/types/appstate/utils.d.ts

@@ -1,7 +1,23 @@
 import type { AppStateCollectionName, WaAppStateSyncKey } from './types';
-import type { WaMediaTransferClient } from '../media/WaMediaTransferClient';
+import type { WaMediaTransferClient } from '../media/transfer/WaMediaTransferClient';
 import type { Proto } from '..';
+/**
+ * Returns `value` typed as a known {@link AppStateCollectionName}, or `null`
+ * when the string is unrecognized.
+ */
 export declare function parseCollectionName(value: string | undefined): AppStateCollectionName | null;
+/**
+ * Reads the 32-bit big-endian epoch encoded in bytes 2..5 of an app-state key id.
+ * Returns `-1` when the key id is too short.
+ */
 export declare function keyEpoch(keyId: Uint8Array): number;
+/**
+ * Picks the highest-epoch app-state sync key from `keys`. Ties are broken by
+ * the lower device id. Returns `null` when the iterable is empty.
+ */
 export declare function pickActiveSyncKey(keys: Iterable<WaAppStateSyncKey>): WaAppStateSyncKey | null;
+/**
+ * Downloads and decrypts an external app-state blob via the media transfer
+ * client. Throws when the reference is missing required fields.
+ */
 export declare function downloadExternalBlobReference(mediaTransfer: WaMediaTransferClient, reference: Proto.IExternalBlobReference): Promise<Uint8Array>;

package/dist/types/appstate-spec.d.ts

@@ -0,0 +1,24 @@
+import { proto, type Proto } from '.';
+import { WA_APPSTATE_SCHEMAS as RAW_WA_APPSTATE_SCHEMAS, type WaAppstateActionKey, type WaAppstateSchema, type WaAppstateValueEnumFields } from '../spec/appstate';
+export { WA_APPSTATE_COLLECTIONS, WA_APPSTATE_SCHEMAS } from '../spec/appstate';
+export type { WaAppstateActionKey, WaAppstateCollection, WaAppstateIndexArgs, WaAppstateIndexPart, WaAppstateIndexValueOf, WaAppstateSchema, WaAppstateScope, WaAppstateValueEnumFields } from '../spec/appstate';
+export type GetByPath<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? GetByPath<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
+export type EnumNamesAt<P extends string> = keyof GetByPath<typeof proto.SyncActionValue, P> & string;
+type EnumValueFor<P extends string, Original> = Original extends ReadonlyArray<unknown> | null | undefined ? ReadonlyArray<EnumNamesAt<P>> | null | undefined : EnumNamesAt<P> | null | undefined;
+type WithEnumStrings<Data, Fields extends WaAppstateValueEnumFields | null> = Fields extends WaAppstateValueEnumFields ? {
+    [K in keyof Data]: K extends keyof Fields ? Fields[K] extends string ? EnumValueFor<Fields[K], Data[K]> : Data[K] : Data[K];
+} : Data;
+export type ValueForSchema<S extends WaAppstateSchema> = S['valueField'] extends keyof Proto.ISyncActionValue ? Pick<Proto.ISyncActionValue, S['valueField'] & keyof Proto.ISyncActionValue> : Proto.ISyncActionValue;
+export type ValueForKey<K extends WaAppstateActionKey> = ValueForSchema<(typeof RAW_WA_APPSTATE_SCHEMAS)[K]>;
+type BaseDataForSchema<S extends WaAppstateSchema> = S['valueField'] extends keyof Proto.ISyncActionValue ? NonNullable<Proto.ISyncActionValue[S['valueField'] & keyof Proto.ISyncActionValue]> : Proto.ISyncActionValue;
+export type DataForSchema<S extends WaAppstateSchema> = WithEnumStrings<BaseDataForSchema<S>, S['valueEnumFields']>;
+export type DataForKey<K extends WaAppstateActionKey> = DataForSchema<(typeof RAW_WA_APPSTATE_SCHEMAS)[K]>;
+export declare const WA_APPSTATE_SCHEMA_BY_ACTION_NAME: Readonly<Record<string, WaAppstateActionKey>>;
+export declare function getAppstateSchemaByActionName(actionName: string): {
+    readonly key: WaAppstateActionKey;
+    readonly schema: WaAppstateSchema;
+} | null;
+export declare function resolveEnumObject(protoEnumPath: string): Record<string, number | string> | null;
+export declare function encodeEnumValue(protoEnumPath: string, name: string): number | null;
+export declare function decodeEnumValue(protoEnumPath: string, value: number): string | null;
+export declare function decodeIndexArgsFromSchema(schema: WaAppstateSchema, parts: readonly string[]): Readonly<Record<string, string | boolean | null>> | null;

package/dist/types/auth/WaAuthClient.d.ts

@@ -1,16 +1,20 @@
 import type { WaAuthClientOptions, WaAuthCredentials, WaAuthSocketOptions, WaSuccessPersistAttributes } from './types';
 import type { Logger } from '../infra/log/types';
 import type { WaAuthStore } from '../store/contracts/auth.store';
+import type { WaPreKeyStore } from '../store/contracts/pre-key.store';
 import type { WaSignalStore } from '../store/contracts/signal.store';
-import type { BinaryNode } from '../transport/types';
+import type { WaNoiseRootCa } from '../transport/noise/WaNoiseCert';
+import type { BinaryNode, WaCommsConfig } from '../transport/types';
 type WaAuthClientDeps = Readonly<{
     readonly logger: Logger;
     readonly authStore: WaAuthStore;
     readonly signalStore: WaSignalStore;
+    readonly preKeyStore: WaPreKeyStore;
     readonly socket: {
         readonly sendNode: (node: BinaryNode) => Promise<void>;
         readonly query: (node: BinaryNode, timeoutMs?: number) => Promise<BinaryNode>;
     };
+    readonly isConnected?: () => boolean;
     readonly callbacks?: {
         readonly onQr?: (qr: string, ttlMs: number) => void;
         readonly onPairingCode?: (code: string) => void;
@@ -19,40 +23,128 @@ type WaAuthClientDeps = Readonly<{
         readonly onError?: (error: Error) => void;
     };
 }>;
+/**
+ * Owns the auth/pairing lifecycle and persistence of {@link WaAuthCredentials}.
+ * Exposed as `client.auth` on a {@link WaClient}.
+ *
+ * Lifecycle: construct with options + dependencies, call
+ * {@link loadOrCreateCredentials} to bring credentials online, then either
+ * follow the QR flow (`onQr` callback) or call {@link requestPairingCode} for
+ * the link-code flow.
+ */
 export declare class WaAuthClient {
     private readonly options;
     private readonly logger;
     private readonly callbacks;
     private readonly authStore;
     private readonly signalStore;
+    private readonly preKeyStore;
+    private readonly isConnected?;
     private readonly qrFlow;
     private readonly pairingFlow;
     private credentials;
+    private versionOverride;
     constructor(options: WaAuthClientOptions, deps: WaAuthClientDeps);
+    /**
+     * Returns a snapshot of auth readiness flags (connection, registration,
+     * pending QR/pairing prompts).
+     */
     getState(connected?: boolean): {
         connected: boolean;
         registered: boolean;
         hasQr: boolean;
         hasPairingCode: boolean;
     };
+    /** Returns the currently-loaded credentials, or `null` before initialization. */
     getCurrentCredentials(): WaAuthCredentials | null;
+    /**
+     * Loads persisted credentials from the auth store, or generates a fresh
+     * set when none exist. Must be called before connecting.
+     */
     loadOrCreateCredentials(): Promise<WaAuthCredentials>;
-    buildCommsConfig(socketOptions: WaAuthSocketOptions): import("../transport/types").WaCommsConfig;
+    /**
+     * Builds a {@link WaCommsConfig} from the current credentials and the
+     * runtime device/transport options – feeds {@link WaComms}.
+     */
+    buildCommsConfig(socketOptions: WaAuthSocketOptions, overrides?: {
+        readonly noiseTrustedRootCa?: WaNoiseRootCa;
+        readonly disableNoiseCertificateChainVerification?: boolean;
+    }): Promise<WaCommsConfig>;
+    /**
+     * One-shot override for the next {@link buildCommsConfig} call: takes
+     * precedence over the user-supplied `version` option, then clears. Used
+     * by the `recoverFromClientTooOld` auto-retry to inject a fresh version
+     * string fetched from `web.whatsapp.com` without mutating the user's
+     * options.
+     */
+    setNextConnectVersion(version: string): void;
+    /** Clears the in-memory QR and pairing sessions without touching storage. */
     clearTransientState(): Promise<void>;
+    /**
+     * Wipes credentials from memory **and** from the auth store. Does
+     * **not** touch the other store domains (signal, app-state, ...) -
+     * those are cleared separately when {@link WaClient.logout} triggers
+     * the server-side logout path, honoring `options.logoutStoreClear`.
+     * Call this manually only when you want to force a re-pair without
+     * going through the server logout IQ.
+     */
     clearStoredCredentials(): Promise<void>;
+    /** Stores the server's noise static key for subsequent handshakes. */
     persistServerStaticKey(serverStaticKey: Uint8Array): Promise<void>;
+    /** Stores the "server holds prekeys" flag; persists only when the value changes. */
     persistServerHasPreKeys(serverHasPreKeys: boolean): Promise<void>;
+    /**
+     * Stores the routing-info blob received from the server. Skips persistence
+     * when the value matches the one already on disk.
+     */
     persistRoutingInfo(routingInfo: Uint8Array): Promise<void>;
+    /** Clears the persisted routing-info blob (used after a routing error). */
     clearRoutingInfo(): Promise<WaAuthCredentials>;
+    /**
+     * Persists the per-connection success attributes from the server (LID,
+     * display name, companion key, last-success ts, props versions, ...). Only
+     * persists when at least one attribute actually changed.
+     */
     persistSuccessAttributes(attributes: WaSuccessPersistAttributes): Promise<void>;
-    requestPairingCode(phoneNumber: string, shouldShowPushNotification?: boolean): Promise<string>;
+    /**
+     * Requests an 8-character pairing code for `phoneNumber` (link-code flow).
+     * Pass `customCode` to suggest a specific code; the server still validates
+     * and may return a different one.
+     *
+     * The client must already be connected – kick off `WaClient.connect()` in
+     * parallel, wait for the `auth_pairing_required` event (or any QR), then
+     * call this. The user then enters the returned code in WhatsApp on their
+     * phone under *Linked Devices → Link with phone number instead*.
+     *
+     * @example
+     * ```ts
+     * // Start the handshake; do NOT await – connect() resolves only after pairing
+     * void client.connect()
+     *
+     * // Wait until the pairing screen is ready on the server side
+     * await new Promise<void>((resolve) => client.once('auth_pairing_required', () => resolve()))
+     *
+     * // Phone number in international format, digits only
+     * const code = await client.auth.requestPairingCode('5511999999999')
+     * console.log(`enter this on your phone: ${code.match(/.{1,4}/g)!.join('-')}`)
+     *
+     * // The `connect()` promise resolves after the user types the code:
+     * await new Promise<void>((resolve) => client.once('auth_paired', () => resolve()))
+     * ```
+     */
+    requestPairingCode(phoneNumber: string, shouldShowPushNotification?: boolean, customCode?: string): Promise<string>;
+    /** Fetches the ISO country code the server resolved for the current account. */
     fetchPairingCountryCodeIso(): Promise<string>;
+    /** Dispatcher: returns `true` when `node` is a pairing-related IQ-set we handled. */
     handleIncomingIqSet(node: BinaryNode): Promise<boolean>;
+    /** Dispatcher: returns `true` when `node` is a link-code companion notification. */
     handleLinkCodeNotification(node: BinaryNode): Promise<boolean>;
+    /** Dispatcher: returns `true` when `node` is a companion-registration refresh notification. */
     handleCompanionRegRefreshNotification(node: BinaryNode): Promise<boolean>;
     private patchCredentials;
     private runHandled;
     private updateCredentials;
+    private requireConnected;
     private requireCredentials;
     private handleError;
 }

package/dist/types/auth/credentials-flow.d.ts

@@ -0,0 +1,21 @@
+import type { WaAuthClientOptions, WaAuthCredentials, WaAuthSocketOptions } from './types';
+import type { Logger } from '../infra/log/types';
+import type { WaAuthStore } from '../store/contracts/auth.store';
+import type { WaPreKeyStore } from '../store/contracts/pre-key.store';
+import type { WaSignalStore } from '../store/contracts/signal.store';
+import type { WaNoiseRootCa } from '../transport/noise/WaNoiseCert';
+import type { WaCommsConfig } from '../transport/types';
+interface WaAuthCredentialsFlowArgs {
+    readonly logger: Logger;
+    readonly authStore: WaAuthStore;
+    readonly signalStore: WaSignalStore;
+    readonly preKeyStore: WaPreKeyStore;
+    readonly skipSignedPreKeySignatureVerification?: boolean;
+}
+export declare function loadOrCreateCredentials(args: WaAuthCredentialsFlowArgs): Promise<WaAuthCredentials>;
+export declare function persistCredentials(args: WaAuthCredentialsFlowArgs, credentials: WaAuthCredentials): Promise<void>;
+export declare function buildCommsConfig(logger: Logger, credentials: WaAuthCredentials, socketOptions: WaAuthSocketOptions, clientOptions: Pick<WaAuthClientOptions, 'deviceBrowser' | 'deviceOsDisplayName' | 'requireFullSync' | 'version' | 'mobileTransport'> & {
+    readonly noiseTrustedRootCa?: WaNoiseRootCa;
+    readonly disableNoiseCertificateChainVerification?: boolean;
+}): Promise<WaCommsConfig>;
+export {};

package/dist/types/auth/pairing/WaPairingFlow.d.ts

@@ -1,4 +1,4 @@
-import type { WaAuthCredentials } from '../types';
+import type { WaAuthCredentials, WaAuthDangerousOptions } from '../types';
 import type { Logger } from '../../infra/log/types';
 import type { BinaryNode } from '../../transport/types';
 interface WaPairingFlowOptions {
@@ -26,6 +26,7 @@ interface WaPairingFlowOptions {
         readonly emitPairingRefresh: (forceManual: boolean) => void;
         readonly emitPaired: (credentials: WaAuthCredentials) => void;
     };
+    readonly dangerous?: WaAuthDangerousOptions;
 }
 export declare class WaPairingFlow {
     private readonly opts;
@@ -33,7 +34,7 @@ export declare class WaPairingFlow {
     constructor(options: WaPairingFlowOptions);
     hasPairingSession(): boolean;
     clearSession(): void;
-    requestPairingCode(phoneNumber: string, shouldShowPushNotification?: boolean): Promise<string>;
+    requestPairingCode(phoneNumber: string, shouldShowPushNotification?: boolean, customCode?: string): Promise<string>;
     fetchPairingCountryCodeIso(): Promise<string>;
     handleIncomingIqSet(node: BinaryNode): Promise<boolean>;
     handleLinkCodeNotification(node: BinaryNode): Promise<boolean>;

package/dist/types/auth/pairing/{WaPairingCodeCrypto.d.ts → pairing-code-crypto.d.ts}

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

package/dist/types/auth/types.d.ts

@@ -1,7 +1,14 @@
 import type { SignalKeyPair } from '../crypto/curves/types';
 import type { Proto } from '..';
 import type { RegistrationInfo, SignedPreKeyRecord } from '../signal/types';
+import type { WaMobileTransportDeviceInfo } from '../transport/noise/WaMobileClientPayload';
 import type { WaCommsConfig, WaProxyTransport } from '../transport/types';
+export type { WaMobileTransportDeviceInfo } from '../transport/noise/WaMobileClientPayload';
+/**
+ * @sensitive Contains private key material (`noiseKeyPair`, `signedPreKey`,
+ * `advSecretKey`, `serverStaticKey`, `companionEncStatic`). Never log, serialize
+ * via `JSON.stringify`, or transmit unencrypted. Persist with encryption-at-rest.
+ */
 export interface WaAuthCredentials {
     readonly noiseKeyPair: SignalKeyPair;
     readonly registrationInfo: RegistrationInfo;
@@ -21,18 +28,98 @@ export interface WaAuthCredentials {
     readonly abPropsVersion?: number;
     readonly connectionLocation?: string;
     readonly accountCreationTs?: number;
+    readonly deviceInfo?: WaMobileTransportDeviceInfo;
+    readonly pushName?: string;
+    readonly yearClass?: number;
+    readonly memClass?: number;
 }
 export type WaAuthSocketOptions = Pick<WaCommsConfig, 'url' | 'urls' | 'protocols' | 'connectTimeoutMs' | 'reconnectIntervalMs' | 'timeoutIntervalMs' | 'maxReconnectAttempts'> & {
     readonly proxy?: {
         readonly ws?: WaProxyTransport;
     };
 };
+/**
+ * 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.
+ */
+export type WaVersionResolver = string | (() => string | Promise<string>);
 export interface WaAuthClientOptions {
+    /**
+     * Browser id advertised during pairing (`'chrome' | 'firefox' | 'safari' |
+     * ...`, see {@link WA_BROWSERS}). Drives the platform id sent in the
+     * link-code stanza and the *Linked Devices* UI label on the phone.
+     * Defaults to `WA_DEFAULTS.DEVICE_BROWSER` (`'chrome'`).
+     */
     readonly deviceBrowser?: string;
+    /**
+     * Override the numeric companion platform id (see
+     * {@link WA_COMPANION_PLATFORM_IDS}). Inferred from `deviceBrowser` when
+     * omitted – set explicitly for non-browser platforms (Electron, UWP, ...).
+     */
     readonly devicePlatform?: string;
+    /**
+     * Human-readable OS name shown in the *Linked Devices* list (`'Windows'`,
+     * `'Mac OS'`, `'Linux'`). Defaults to the current runtime's OS.
+     */
     readonly deviceOsDisplayName?: string;
+    /**
+     * When `true`, request a full history download from the primary device on
+     * pairing instead of just recent messages. Off by default.
+     */
     readonly requireFullSync?: boolean;
-    readonly version?: string;
+    /**
+     * 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.
+     */
+    readonly version?: WaVersionResolver;
+    /**
+     * **Dangerous escape hatches** – each flag disables a security check.
+     * Do not enable in production.
+     */
+    readonly dangerous?: WaAuthDangerousOptions;
+    /**
+     * Mobile-transport overrides (TCP socket, device info). Set this to
+     * connect via the WhatsApp Mobile protocol instead of Web – see
+     * {@link WaMobileTransportOptions}.
+     */
+    readonly mobileTransport?: WaMobileTransportOptions;
+}
+export interface WaMobileTransportOptions {
+    readonly deviceInfo: WaMobileTransportDeviceInfo;
+    readonly tcpUrl?: string;
+    readonly passive?: boolean;
+    readonly pushName?: string;
+    readonly yearClass?: number;
+    readonly memClass?: number;
+}
+export interface WaAuthDangerousOptions {
+    /**
+     * Skip the noise certificate-chain verification during the handshake.
+     * The server's static key will be accepted without proof that it was
+     * issued by a trusted root.
+     */
+    readonly disableNoiseCertificateChainVerification?: boolean;
+    /**
+     * Skip the XEdDSA account-signature check on the `pair-success` ADV
+     * identity payload, which normally proves the primary device signed off
+     * on this companion.
+     */
+    readonly disableAdvSignatureVerification?: boolean;
+    /**
+     * Skip the HMAC check on the `pair-success` stanza that ties the ADV
+     * payload to the shared pairing secret.
+     */
+    readonly disablePairSuccessHmacVerification?: boolean;
+    /**
+     * Skip the XEdDSA signature check on the locally stored signed pre-key
+     * during credential load. Corrupt or forged credentials will be accepted.
+     */
+    readonly disableSignedPreKeySignatureVerification?: boolean;
 }
 export interface WaSuccessPersistAttributes {
     readonly meLid?: string;