zapo-js 1.8.2 → 1.10.0

package/dist/store/memory/privacy-token.store.d.ts

@@ -1,6 +1,6 @@
 import type { WaPrivacyTokenStore, WaStoredPrivacyTokenRecord } from '../contracts/privacy-token.store';
 export declare class WaPrivacyTokenMemoryStore implements WaPrivacyTokenStore {
-    private readonly records;
+    protected readonly records: Map<string, WaStoredPrivacyTokenRecord>;
     private readonly maxEntries;
     constructor(maxEntries?: number);
     upsert(record: WaStoredPrivacyTokenRecord): Promise<void>;
@@ -9,5 +9,11 @@ export declare class WaPrivacyTokenMemoryStore implements WaPrivacyTokenStore {
     deleteByJid(jid: string): Promise<number>;
     clear(): Promise<void>;
     destroy(): Promise<void>;
+    /** Runs with the jid of every read hit and write. No-op unless a subclass tracks access. */
+    protected onEntryAccess(jid: string): void;
+    /** Runs with the jid of every deleted or cap-evicted record. */
+    protected onEntryRemove(jid: string): void;
+    protected onEntriesClear(): void;
+    private readonly onEvict;
     private mergeRecord;
 }

package/dist/store/memory/privacy-token.store.js

@@ -1,38 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaPrivacyTokenMemoryStore = void 0;
+const coercion_1 = require("../../util/coercion");
 const collections_1 = require("../../util/collections");
 const DEFAULT_MAX_ENTRIES = 10000;
 class WaPrivacyTokenMemoryStore {
-    constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    constructor(maxEntries) {
+        this.onEvict = (jid) => this.onEntryRemove(jid);
         this.records = new Map();
-        this.maxEntries = maxEntries;
+        this.maxEntries = (0, coercion_1.resolvePositive)(maxEntries, DEFAULT_MAX_ENTRIES, 'WaPrivacyTokenMemoryStore.maxEntries');
     }
     async upsert(record) {
         const existing = this.records.get(record.jid);
         const merged = existing ? this.mergeRecord(existing, record) : record;
-        (0, collections_1.setBoundedMapEntry)(this.records, record.jid, merged, this.maxEntries);
+        (0, collections_1.setBoundedMapEntry)(this.records, record.jid, merged, this.maxEntries, this.onEvict);
+        this.onEntryAccess(record.jid);
     }
     async upsertBatch(records) {
         for (let i = 0; i < records.length; i += 1) {
             const record = records[i];
             const existing = this.records.get(record.jid);
             const merged = existing ? this.mergeRecord(existing, record) : record;
-            (0, collections_1.setBoundedMapEntry)(this.records, record.jid, merged, this.maxEntries);
+            (0, collections_1.setBoundedMapEntry)(this.records, record.jid, merged, this.maxEntries, this.onEvict);
+            this.onEntryAccess(record.jid);
         }
     }
     async getByJid(jid) {
-        return this.records.get(jid) ?? null;
+        const record = this.records.get(jid);
+        if (record === undefined)
+            return null;
+        this.onEntryAccess(jid);
+        return record;
     }
     async deleteByJid(jid) {
-        return this.records.delete(jid) ? 1 : 0;
+        if (!this.records.delete(jid))
+            return 0;
+        this.onEntryRemove(jid);
+        return 1;
     }
     async clear() {
         this.records.clear();
+        this.onEntriesClear();
     }
     async destroy() {
-        this.records.clear();
+        await this.clear();
     }
+    /** Runs with the jid of every read hit and write. No-op unless a subclass tracks access. */
+    onEntryAccess(jid) { }
+    /** Runs with the jid of every deleted or cap-evicted record. */
+    onEntryRemove(jid) { }
+    onEntriesClear() { }
     mergeRecord(existing, incoming) {
         return {
             jid: incoming.jid,

package/dist/store/memory/sender-key.store.d.ts

@@ -5,8 +5,8 @@ export interface WaSenderKeyMemoryStoreOptions {
     readonly maxSenderDistributions?: number;
 }
 export declare class SenderKeyMemoryStore implements WaSenderKeyStoreContract {
-    private readonly senderKeys;
-    private readonly senderDistributions;
+    protected readonly senderKeys: Map<string, SenderKeyRecord>;
+    protected readonly senderDistributions: Map<string, SenderKeyDistributionRecord>;
     private readonly maxSenderKeys;
     private readonly maxSenderDistributions;
     constructor(options?: WaSenderKeyMemoryStoreOptions);
@@ -22,6 +22,16 @@ export declare class SenderKeyMemoryStore implements WaSenderKeyStoreContract {
     deleteDeviceSenderKey(target: SignalAddress, groupId?: string): Promise<number>;
     markForgetSenderKey(groupId: string, participants: readonly SignalAddress[]): Promise<number>;
     clear(): Promise<void>;
+    /**
+     * Runs with the map and key of every point-read hit and write (the group
+     * scan does not count). No-op unless a subclass tracks access.
+     */
+    protected onEntryAccess(entries: Map<string, unknown>, key: string): void;
+    /** Runs with the map and key of every deleted or cap-evicted entry. */
+    protected onEntryRemove(entries: Map<string, unknown>, key: string): void;
+    protected onEntriesClear(): void;
+    private readonly onSenderKeyEvict;
+    private readonly onDistributionEvict;
     private deleteMatching;
     private makeKey;
 }

package/dist/store/memory/sender-key.store.js

@@ -10,20 +10,28 @@ const DEFAULT_SENDER_KEY_STORE_LIMITS = Object.freeze({
 });
 class SenderKeyMemoryStore {
     constructor(options = {}) {
+        this.onSenderKeyEvict = (key) => this.onEntryRemove(this.senderKeys, key);
+        this.onDistributionEvict = (key) => this.onEntryRemove(this.senderDistributions, key);
         this.senderKeys = new Map();
         this.senderDistributions = new Map();
         this.maxSenderKeys = (0, coercion_1.resolvePositive)(options.maxSenderKeys, DEFAULT_SENDER_KEY_STORE_LIMITS.senderKeys, 'WaSenderKeyMemoryStoreOptions.maxSenderKeys');
         this.maxSenderDistributions = (0, coercion_1.resolvePositive)(options.maxSenderDistributions, DEFAULT_SENDER_KEY_STORE_LIMITS.senderDistributions, 'WaSenderKeyMemoryStoreOptions.maxSenderDistributions');
     }
     async upsertSenderKey(record) {
-        (0, collections_1.setBoundedMapEntry)(this.senderKeys, this.makeKey(record.groupId, record.sender), record, this.maxSenderKeys);
+        const key = this.makeKey(record.groupId, record.sender);
+        (0, collections_1.setBoundedMapEntry)(this.senderKeys, key, record, this.maxSenderKeys, this.onSenderKeyEvict);
+        this.onEntryAccess(this.senderKeys, key);
     }
     async upsertSenderKeyDistribution(record) {
-        (0, collections_1.setBoundedMapEntry)(this.senderDistributions, this.makeKey(record.groupId, record.sender), record, this.maxSenderDistributions);
+        const key = this.makeKey(record.groupId, record.sender);
+        (0, collections_1.setBoundedMapEntry)(this.senderDistributions, key, record, this.maxSenderDistributions, this.onDistributionEvict);
+        this.onEntryAccess(this.senderDistributions, key);
     }
     async upsertSenderKeyDistributions(records) {
         for (const record of records) {
-            (0, collections_1.setBoundedMapEntry)(this.senderDistributions, this.makeKey(record.groupId, record.sender), record, this.maxSenderDistributions);
+            const key = this.makeKey(record.groupId, record.sender);
+            (0, collections_1.setBoundedMapEntry)(this.senderDistributions, key, record, this.maxSenderDistributions, this.onDistributionEvict);
+            this.onEntryAccess(this.senderDistributions, key);
         }
     }
     async getGroupSenderKeyList(groupId) {
@@ -45,14 +53,25 @@ class SenderKeyMemoryStore {
         };
     }
     async getDeviceSenderKey(groupId, sender) {
-        const record = this.senderKeys.get(this.makeKey(groupId, sender));
-        return record ?? null;
+        const key = this.makeKey(groupId, sender);
+        const record = this.senderKeys.get(key);
+        if (record === undefined)
+            return null;
+        this.onEntryAccess(this.senderKeys, key);
+        return record;
     }
     async getDeviceSenderKeyDistributions(groupId, senders) {
         const records = new Array(senders.length);
         for (let index = 0; index < senders.length; index += 1) {
-            records[index] =
-                this.senderDistributions.get(this.makeKey(groupId, senders[index])) ?? null;
+            const key = this.makeKey(groupId, senders[index]);
+            const record = this.senderDistributions.get(key);
+            if (record === undefined) {
+                records[index] = null;
+            }
+            else {
+                this.onEntryAccess(this.senderDistributions, key);
+                records[index] = record;
+            }
         }
         return records;
     }
@@ -74,7 +93,16 @@ class SenderKeyMemoryStore {
     async clear() {
         this.senderKeys.clear();
         this.senderDistributions.clear();
+        this.onEntriesClear();
     }
+    /**
+     * Runs with the map and key of every point-read hit and write (the group
+     * scan does not count). No-op unless a subclass tracks access.
+     */
+    onEntryAccess(entries, key) { }
+    /** Runs with the map and key of every deleted or cap-evicted entry. */
+    onEntryRemove(entries, key) { }
+    onEntriesClear() { }
     deleteMatching(map, target, groupId) {
         let deleted = 0;
         const targetAddressKey = (0, jid_1.signalAddressKey)(target);
@@ -83,6 +111,7 @@ class SenderKeyMemoryStore {
             const sameAddress = (0, jid_1.signalAddressKey)(record.sender) === targetAddressKey;
             if (sameGroup && sameAddress) {
                 map.delete(key);
+                this.onEntryRemove(map, key);
                 deleted += 1;
             }
         }

package/dist/store/memory/session.store.d.ts

@@ -4,7 +4,7 @@ export interface WaSessionMemoryStoreOptions {
     readonly maxSessions?: number;
 }
 export declare class WaSessionMemoryStore implements WaSessionStoreContract {
-    private readonly signalSessions;
+    protected readonly signalSessions: Map<string, SignalSessionRecord>;
     private readonly maxSessions;
     constructor(options?: WaSessionMemoryStoreOptions);
     hasSession(address: SignalAddress): Promise<boolean>;
@@ -18,4 +18,10 @@ export declare class WaSessionMemoryStore implements WaSessionStoreContract {
     }[]): Promise<void>;
     deleteSession(address: SignalAddress): Promise<void>;
     clear(): Promise<void>;
+    /** Runs with the key of every read hit and write. No-op unless a subclass tracks access. */
+    protected onEntryAccess(key: string): void;
+    /** Runs with the key of every deleted or cap-evicted entry. */
+    protected onEntryRemove(key: string): void;
+    protected onEntriesClear(): void;
+    private readonly onEvict;
 }

package/dist/store/memory/session.store.js

@@ -7,43 +7,77 @@ const collections_1 = require("../../util/collections");
 const DEFAULT_MAX_SESSIONS = 8192;
 class WaSessionMemoryStore {
     constructor(options = {}) {
+        this.onEvict = (key) => this.onEntryRemove(key);
         this.signalSessions = new Map();
         this.maxSessions = (0, coercion_1.resolvePositive)(options.maxSessions, DEFAULT_MAX_SESSIONS, 'WaSessionMemoryStoreOptions.maxSessions');
     }
     async hasSession(address) {
-        return this.signalSessions.has((0, jid_1.signalAddressKey)(address));
+        const key = (0, jid_1.signalAddressKey)(address);
+        if (!this.signalSessions.has(key))
+            return false;
+        this.onEntryAccess(key);
+        return true;
     }
     async hasSessions(addresses) {
         const result = new Array(addresses.length);
         for (let i = 0; i < addresses.length; i += 1) {
-            result[i] = this.signalSessions.has((0, jid_1.signalAddressKey)(addresses[i]));
+            const key = (0, jid_1.signalAddressKey)(addresses[i]);
+            const found = this.signalSessions.has(key);
+            if (found)
+                this.onEntryAccess(key);
+            result[i] = found;
         }
         return result;
     }
     async getSession(address) {
-        return this.signalSessions.get((0, jid_1.signalAddressKey)(address)) ?? null;
+        const key = (0, jid_1.signalAddressKey)(address);
+        const session = this.signalSessions.get(key);
+        if (session === undefined)
+            return null;
+        this.onEntryAccess(key);
+        return session;
     }
     async getSessionsBatch(addresses) {
         const result = new Array(addresses.length);
         for (let i = 0; i < addresses.length; i += 1) {
-            result[i] = this.signalSessions.get((0, jid_1.signalAddressKey)(addresses[i])) ?? null;
+            const key = (0, jid_1.signalAddressKey)(addresses[i]);
+            const session = this.signalSessions.get(key);
+            if (session === undefined) {
+                result[i] = null;
+            }
+            else {
+                this.onEntryAccess(key);
+                result[i] = session;
+            }
         }
         return result;
     }
     async setSession(address, session) {
-        (0, collections_1.setBoundedMapEntry)(this.signalSessions, (0, jid_1.signalAddressKey)(address), session, this.maxSessions);
+        const key = (0, jid_1.signalAddressKey)(address);
+        (0, collections_1.setBoundedMapEntry)(this.signalSessions, key, session, this.maxSessions, this.onEvict);
+        this.onEntryAccess(key);
     }
     async setSessionsBatch(entries) {
         for (let index = 0; index < entries.length; index += 1) {
             const entry = entries[index];
-            (0, collections_1.setBoundedMapEntry)(this.signalSessions, (0, jid_1.signalAddressKey)(entry.address), entry.session, this.maxSessions);
+            const key = (0, jid_1.signalAddressKey)(entry.address);
+            (0, collections_1.setBoundedMapEntry)(this.signalSessions, key, entry.session, this.maxSessions, this.onEvict);
+            this.onEntryAccess(key);
         }
     }
     async deleteSession(address) {
-        this.signalSessions.delete((0, jid_1.signalAddressKey)(address));
+        const key = (0, jid_1.signalAddressKey)(address);
+        if (this.signalSessions.delete(key))
+            this.onEntryRemove(key);
     }
     async clear() {
         this.signalSessions.clear();
+        this.onEntriesClear();
     }
+    /** Runs with the key of every read hit and write. No-op unless a subclass tracks access. */
+    onEntryAccess(key) { }
+    /** Runs with the key of every deleted or cap-evicted entry. */
+    onEntryRemove(key) { }
+    onEntriesClear() { }
 }
 exports.WaSessionMemoryStore = WaSessionMemoryStore;

package/dist/store/types.d.ts

@@ -364,10 +364,11 @@ export interface WaCreateStoreOptions<B extends string = string, TBackends exten
     /**
      * Opt-in in-process read-through cache in front of a *persistent* backend
      * for the hot signal domains. Each enabled domain wraps its backend store
-     * with a bounded-LRU L1 (the in-tree memory provider) so repeated reads of
+     * with a bounded L1 (the in-tree memory provider) so repeated reads of
      * the same peer on the send/recv path skip the backend round-trip; writes
      * stay write-through (or invalidate-on-write for `privacyToken`) so the
-     * backend remains authoritative.
+     * backend remains authoritative. Entries leave the L1 through the
+     * `limits` cap and, when set, the `ttlMs` idle TTL.
      *
      * A domain flag is a no-op unless that domain resolves to a real backend
      * in {@link providers} - caching a `'memory'`/`'none'` provider in front of
@@ -417,8 +418,10 @@ export interface WaCreateStoreOptions<B extends string = string, TBackends exten
         /** Cache trusted-contact tokens (jid→record). Invalidate-on-write. */
         readonly privacyToken?: boolean;
         /**
-         * Per-domain L1 entry caps (LRU eviction once exceeded). Defaults to
-         * the matching memory-provider default when unset.
+         * Per-domain L1 entry caps. Past the cap the least recently written
+         * entry goes or, when the domain has a `ttlMs`, the least recently
+         * used one (recency counted in sweep ticks). Defaults to the matching
+         * memory-provider default when unset.
          */
         readonly limits?: {
             readonly session?: number;
@@ -426,6 +429,42 @@ export interface WaCreateStoreOptions<B extends string = string, TBackends exten
             readonly senderKey?: number;
             readonly privacyToken?: number;
         };
+        /**
+         * Per-domain L1 idle TTLs in milliseconds, each a safe integer of at
+         * least 1_000. An entry neither read nor written for this long leaves
+         * the L1, so a long-lived process keeps the peers it is actively
+         * talking to instead of every peer seen since boot. Unset (the
+         * default) keeps entries until `limits` evicts them. A TTL on a
+         * domain that gets no L1 (flag off, or a `'memory'`/`'none'`
+         * provider) is ignored with a warning on the store `logger`.
+         *
+         * Idle time is counted in ticks of one sweep timer per store, whose
+         * period is the smallest `ttlMs / 2` clamped to [1 s, 60 s], so
+         * wall-clock steps never expire or keep an entry. An entry goes after
+         * at least `ttlMs` idle and less than `ttlMs` plus two periods.
+         *
+         * The TTL bounds residency, not freshness. The L1 stays coherent with
+         * the backend (write-through, or invalidate-on-write), so expiry never
+         * changes what a read returns: an expired entry is re-read from the
+         * backend on its next use, and the backend rows are never touched.
+         * Size it against that miss cost - each expiry turns the next lookup
+         * of that peer into one backend read.
+         *
+         * @example
+         * ```ts
+         * cacheLayer: {
+         *     session: true,
+         *     identity: true,
+         *     ttlMs: { sessionMs: 30 * 60_000, identityMs: 30 * 60_000 }
+         * }
+         * ```
+         */
+        readonly ttlMs?: {
+            readonly sessionMs?: number;
+            readonly identityMs?: number;
+            readonly senderKeyMs?: number;
+            readonly privacyTokenMs?: number;
+        };
     };
     /**
      * Memory-store tuning for the built-in `'memory'` providers. `limits`

package/dist/transport/node/WaMobileTcpSocket.d.ts

@@ -16,7 +16,9 @@ export declare class WaMobileTcpSocket implements RawWebSocket {
     private closedReason;
     private closedClean;
     private forceCloseTimer;
-    constructor(url: string, _protocols?: unknown, _options?: WaRawWebSocketInit);
+    constructor(url: string, _protocols?: unknown, options?: WaRawWebSocketInit);
+    private markOpen;
+    private emitMessage;
     send(data: string | ArrayBuffer | Uint8Array): void;
     close(code?: number, reason?: string): void;
 }

package/dist/transport/node/WaMobileTcpSocket.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaMobileTcpSocketCtor = exports.WaMobileTcpSocket = void 0;
 const node_net_1 = require("node:net");
 const constants_1 = require("../../protocol/constants");
+const proxy_1 = require("../proxy");
 const bytes_1 = require("../../util/bytes");
 /**
  * `RawWebSocket`-shaped adapter over a raw Node TCP socket. Used by the
@@ -10,7 +11,7 @@ const bytes_1 = require("../../util/bytes");
  * `tcp://host:port` URLs.
  */
 class WaMobileTcpSocket {
-    constructor(url, _protocols, _options) {
+    constructor(url, _protocols, options) {
         this.binaryType = 'arraybuffer';
         this.readyState = constants_1.WA_READY_STATES.CONNECTING;
         this.onopen = null;
@@ -22,19 +23,55 @@ class WaMobileTcpSocket {
         this.closedClean = true;
         this.forceCloseTimer = null;
         const { host, port } = parseTcpUrl(url);
-        this.socket = (0, node_net_1.connect)({ host, port });
+        const proxy = (0, proxy_1.toTcpProxyEndpoint)(options?.agent);
+        this.socket = proxy
+            ? (0, node_net_1.connect)({ host: proxy.hostname, port: proxy.port })
+            : (0, node_net_1.connect)({ host, port });
+        let tunnelReady = !proxy;
+        let proxyResponse = new Uint8Array(0);
         this.socket.on('connect', () => {
             if (this.readyState !== constants_1.WA_READY_STATES.CONNECTING)
                 return;
-            this.readyState = constants_1.WA_READY_STATES.OPEN;
-            this.onopen?.({});
+            if (proxy) {
+                const authority = `${host}:${port}`;
+                const lines = [
+                    `CONNECT ${authority} HTTP/1.1`,
+                    `Host: ${authority}`,
+                    'Proxy-Connection: Keep-Alive'
+                ];
+                if (proxy.authorization)
+                    lines.push(`Proxy-Authorization: ${proxy.authorization}`);
+                this.socket.write(bytes_1.TEXT_ENCODER.encode(`${lines.join('\r\n')}\r\n\r\n`));
+                return;
+            }
+            this.markOpen();
         });
         this.socket.on('data', (chunk) => {
-            if (!this.onmessage || this.readyState !== constants_1.WA_READY_STATES.OPEN)
+            if (!tunnelReady && proxy) {
+                proxyResponse = (0, bytes_1.concatBytes)([proxyResponse, chunk]);
+                const headerEnd = findHttpHeaderEnd(proxyResponse);
+                const scanned = headerEnd === -1 ? proxyResponse.byteLength : headerEnd;
+                if (scanned > MAX_PROXY_HEADER_BYTES) {
+                    this.socket.destroy(new Error('WaMobileTcpSocket: proxy response headers too large'));
+                    return;
+                }
+                if (headerEnd === -1) {
+                    return;
+                }
+                const statusLine = bytes_1.TEXT_DECODER.decode(proxyResponse.subarray(0, headerEnd)).split('\r\n')[0];
+                if (!/^HTTP\/1\.[01] 2\d\d(?:\s|$)/.test(statusLine)) {
+                    this.socket.destroy(new Error(`WaMobileTcpSocket: proxy CONNECT failed (${statusLine})`));
+                    return;
+                }
+                const remaining = proxyResponse.subarray(headerEnd + 4);
+                proxyResponse = new Uint8Array(0);
+                tunnelReady = true;
+                this.markOpen();
+                if (remaining.byteLength > 0)
+                    this.emitMessage(remaining);
                 return;
-            const copy = new Uint8Array(chunk.byteLength);
-            copy.set(chunk);
-            this.onmessage({ data: copy });
+            }
+            this.emitMessage(chunk);
         });
         this.socket.on('error', (err) => {
             this.closedClean = false;
@@ -56,6 +93,19 @@ class WaMobileTcpSocket {
             });
         });
     }
+    markOpen() {
+        if (this.readyState !== constants_1.WA_READY_STATES.CONNECTING)
+            return;
+        this.readyState = constants_1.WA_READY_STATES.OPEN;
+        this.onopen?.({});
+    }
+    emitMessage(chunk) {
+        if (!this.onmessage || this.readyState !== constants_1.WA_READY_STATES.OPEN)
+            return;
+        const copy = new Uint8Array(chunk.byteLength);
+        copy.set(chunk);
+        this.onmessage({ data: copy });
+    }
     send(data) {
         if (this.readyState !== constants_1.WA_READY_STATES.OPEN) {
             throw new Error('WaMobileTcpSocket: send() called on non-OPEN socket');
@@ -89,6 +139,16 @@ class WaMobileTcpSocket {
     }
 }
 exports.WaMobileTcpSocket = WaMobileTcpSocket;
+/** Cap on the CONNECT response headers buffered before the tunnel is rejected. */
+const MAX_PROXY_HEADER_BYTES = 65536;
+function findHttpHeaderEnd(bytes) {
+    for (let i = 3; i < bytes.byteLength; i += 1) {
+        if (bytes[i - 3] === 13 && bytes[i - 2] === 10 && bytes[i - 1] === 13 && bytes[i] === 10) {
+            return i - 3;
+        }
+    }
+    return -1;
+}
 function parseTcpUrl(url) {
     let work = url;
     if (work.startsWith('tcp://')) {

package/dist/transport/noise/WaMobileClientPayload.d.ts

@@ -1,5 +1,25 @@
 import { type Proto } from '../../proto';
+/**
+ * Distribution channel advertised by an iOS login (`UserAgent.distributionChannel`).
+ * iOS-only – Android leaves the field unset. `appstore` is the normal
+ * production install; `testflight`/`internal` mark beta builds.
+ */
+export type WaMobileDistributionChannel = 'appstore' | 'website' | 'testflight' | 'internal';
 export interface WaMobileTransportDeviceInfo {
+    /**
+     * Operating system the login payload impersonates. `android` (the default,
+     * for backwards compatibility) advertises the `ANDROID`/`SMB_ANDROID`
+     * platform and fills the Android-only `mcc`/`mnc`/`deviceBoard` fields.
+     * `ios` advertises `IOS`/`SMB_IOS`, omits those Android-only fields (the
+     * real iPhone client never sends them) and carries `distributionChannel`
+     * instead.
+     *
+     * Field mapping differs by OS and must match the real client:
+     * - **Android** `device` = a device codename (e.g. `moto_g52`).
+     * - **iOS** `device` = the marketing name (e.g. `iPhone 15 Pro`) while
+     *   {@link deviceModelType} carries the raw machine id (`iPhone16,1`).
+     */
+    readonly os?: 'android' | 'ios';
     readonly manufacturer: string;
     readonly device: string;
     readonly osVersion: string;
@@ -12,6 +32,8 @@ export interface WaMobileTransportDeviceInfo {
     readonly phoneId?: string;
     readonly deviceBoard?: string;
     readonly deviceModelType?: string;
+    /** iOS distribution channel; ignored for Android. Defaults to `appstore`. */
+    readonly distributionChannel?: WaMobileDistributionChannel;
     readonly business?: boolean;
 }
 export interface WaMobileLoginPayloadConfig {

package/dist/transport/noise/WaMobileClientPayload.js

@@ -16,6 +16,20 @@ function parseAppVersion(version) {
         quaternary: at(3)
     };
 }
+function distributionChannelId(channel) {
+    const { DistributionChannel } = _proto_1.proto.ClientPayload.UserAgent;
+    switch (channel) {
+        case 'website':
+            return DistributionChannel.WEBSITE;
+        case 'testflight':
+            return DistributionChannel.TESTFLIGHT;
+        case 'internal':
+            return DistributionChannel.INTERNAL;
+        case 'appstore':
+        case undefined:
+            return DistributionChannel.APPSTORE;
+    }
+}
 /**
  * Builds the encoded {@link Proto.ClientPayload} bytes the WhatsApp Mobile
  * transport sends after the noise login handshake. Throws when
@@ -27,14 +41,18 @@ function buildMobileLoginPayload(config) {
     }
     const info = config.deviceInfo;
     const version = parseAppVersion(info.appVersion);
-    const userAgent = {
-        platform: info.business
+    const isIos = info.os === 'ios';
+    const platform = isIos
+        ? info.business
+            ? _proto_1.proto.ClientPayload.UserAgent.Platform.SMB_IOS
+            : _proto_1.proto.ClientPayload.UserAgent.Platform.IOS
+        : info.business
             ? _proto_1.proto.ClientPayload.UserAgent.Platform.SMB_ANDROID
-            : _proto_1.proto.ClientPayload.UserAgent.Platform.ANDROID,
+            : _proto_1.proto.ClientPayload.UserAgent.Platform.ANDROID;
+    const userAgent = {
+        platform,
         releaseChannel: _proto_1.proto.ClientPayload.UserAgent.ReleaseChannel.RELEASE,
         appVersion: version,
-        mcc: info.mcc ?? '000',
-        mnc: info.mnc ?? '000',
         osVersion: info.osVersion,
         manufacturer: info.manufacturer,
         device: info.device,
@@ -43,8 +61,10 @@ function buildMobileLoginPayload(config) {
         localeLanguageIso6391: info.localeLanguageIso6391 ?? 'en',
         localeCountryIso31661Alpha2: info.localeCountryIso31661Alpha2 ?? 'US',
         deviceType: _proto_1.proto.ClientPayload.UserAgent.DeviceType.PHONE,
-        deviceBoard: info.deviceBoard,
-        deviceModelType: info.deviceModelType
+        deviceModelType: info.deviceModelType,
+        ...(isIos
+            ? { distributionChannel: distributionChannelId(info.distributionChannel) }
+            : { mcc: info.mcc ?? '000', mnc: info.mnc ?? '000', deviceBoard: info.deviceBoard })
     };
     return _proto_1.proto.ClientPayload.encode({
         passive: config.passive === true,

package/dist/transport/proxy.d.ts

@@ -9,3 +9,27 @@ export declare function isProxyTransport(value: unknown): value is WaProxyTransp
 export declare function toProxyDispatcher(proxy: WaProxyTransport | undefined): WaProxyDispatcher | undefined;
 /** Narrows `proxy` to {@link WaProxyAgent} or returns `undefined`. */
 export declare function toProxyAgent(proxy: WaProxyTransport | undefined): WaProxyAgent | undefined;
+/**
+ * HTTP CONNECT endpoint a raw TCP transport dials to reach its destination.
+ *
+ * @sensitive Contains proxy credentials (`authorization`). Never log, serialize
+ * via `JSON.stringify`, or transmit unencrypted. Persist with encryption-at-rest.
+ */
+export interface WaTcpProxyEndpoint {
+    readonly hostname: string;
+    readonly port: number;
+    /** Ready-to-send `Proxy-Authorization` value when the proxy url carries credentials. */
+    readonly authorization?: string;
+}
+/**
+ * Resolves the proxy endpoint a raw TCP transport tunnels through with HTTP
+ * CONNECT.
+ *
+ * Returns `undefined` only when no proxy is configured. Proxy shapes the tunnel
+ * cannot honour throw instead of resolving to `undefined`, because dropping one
+ * silently would dial the destination directly – the opposite of what a
+ * deployment that pins its egress to a proxy asked for.
+ */
+export declare function toTcpProxyEndpoint(proxy: WaProxyTransport | undefined): WaTcpProxyEndpoint | undefined;
+/** Throws when {@link toTcpProxyEndpoint} cannot honour `proxy`. */
+export declare function assertTcpProxySupported(proxy: WaProxyTransport | undefined): void;