zapo-js 1.8.2 → 1.10.0

package/dist/esm/store/createStore.js

@@ -35,6 +35,7 @@ import { WaSignalMemoryStore } from './memory/signal.store.js';
 import { WaThreadMemoryStore } from './memory/thread.store.js';
 import { NOOP_CHAT_METADATA_STORE, NOOP_CONTACT_STORE, NOOP_DEVICE_LIST_STORE, NOOP_GROUP_METADATA_STORE, NOOP_MESSAGE_SECRET_STORE, NOOP_MESSAGE_STORE, NOOP_RETRY_STORE, NOOP_THREAD_STORE } from './noop.store.js';
 import { resolvePositive } from '../util/coercion.js';
+import { IdleSweepClock, resolveIdleSweepPeriodMs } from '../util/collections.js';
 import { toError } from '../util/primitives.js';
 const DEFAULT_CACHE_TTLS_MS = Object.freeze({
     retryMs: 60 * 1000,
@@ -56,6 +57,8 @@ const REQUIRED_PROVIDER_DOMAINS = [
     'contacts',
     'privacyToken'
 ];
+const CACHE_LAYER_DOMAINS = ['session', 'identity', 'senderKey', 'privacyToken'];
+const MIN_CACHE_LAYER_TTL_MS = 1000;
 function hasDestroy(value) {
     return (!!value &&
         typeof value === 'object' &&
@@ -70,6 +73,37 @@ async function destroyIfSupported(value) {
 function usesBackend(provider) {
     return !!provider && provider !== 'memory' && provider !== 'none';
 }
+/**
+ * Validates `cacheLayer.ttlMs` and hands each domain that gets an L1 its idle
+ * expiry, all on one clock. A TTL on a domain without an L1 is warned and dropped.
+ */
+function resolveCacheLayerExpiry(cacheLayer, providers, logger) {
+    const ttls = [];
+    for (const domain of CACHE_LAYER_DOMAINS) {
+        const ttlMs = cacheLayer.ttlMs?.[`${domain}Ms`];
+        if (ttlMs === undefined)
+            continue;
+        if (!Number.isSafeInteger(ttlMs) || ttlMs < MIN_CACHE_LAYER_TTL_MS) {
+            throw new Error(`cacheLayer.ttlMs.${domain}Ms must be a safe integer >= ${MIN_CACHE_LAYER_TTL_MS}`);
+        }
+        if (cacheLayer[domain] && usesBackend(providers[domain])) {
+            ttls.push({ domain, ttlMs });
+            continue;
+        }
+        logger?.warn('cacheLayer ttl ignored: domain has no L1', {
+            domain,
+            cached: cacheLayer[domain] === true,
+            provider: providers[domain] ?? 'memory'
+        });
+    }
+    const expiry = {};
+    if (ttls.length === 0)
+        return expiry;
+    const clock = new IdleSweepClock(resolveIdleSweepPeriodMs(ttls.map((entry) => entry.ttlMs)));
+    for (const { domain, ttlMs } of ttls)
+        expiry[domain] = { clock, ttlMs };
+    return expiry;
+}
 function resolveStore(sessionId, backends, provider, domain, kind, fallback) {
     if (!provider || provider === 'memory' || provider === 'none') {
         return fallback();
@@ -112,6 +146,7 @@ export function createStore(options) {
         deviceList: resolvePositive(options.memory?.cacheTtlMs?.deviceListMs, DEFAULT_CACHE_TTLS_MS.deviceListMs, 'memory.cacheTtlMs.deviceListMs'),
         messageSecret: resolvePositive(options.memory?.cacheTtlMs?.messageSecretMs, DEFAULT_CACHE_TTLS_MS.messageSecretMs, 'memory.cacheTtlMs.messageSecretMs')
     });
+    const cacheLayerExpiry = resolveCacheLayerExpiry(cacheLayer, providers, storeLogger);
     const sessions = new Map();
     const pendingSessionDestroys = new Set();
     let storeDestroyed = false;
@@ -208,20 +243,20 @@ export function createStore(options) {
             const signalStore = withSignalLock(rawSignal);
             const preKeyStore = withPreKeyLock(rawPreKey);
             const sessionStore = withSessionLock(cacheLayer.session && usesBackend(providers.session)
-                ? withSessionCache(rawSession, cacheLayer.limits?.session)
+                ? withSessionCache(rawSession, cacheLayer.limits?.session, cacheLayerExpiry.session)
                 : rawSession);
             const identityStore = withIdentityLock(cacheLayer.identity && usesBackend(providers.identity)
-                ? withIdentityCache(rawIdentity, cacheLayer.limits?.identity)
+                ? withIdentityCache(rawIdentity, cacheLayer.limits?.identity, cacheLayerExpiry.identity)
                 : rawIdentity);
             const senderKeyStore = withSenderKeyLock(cacheLayer.senderKey && usesBackend(providers.senderKey)
-                ? withSenderKeyCache(rawSenderKey, cacheLayer.limits?.senderKey)
+                ? withSenderKeyCache(rawSenderKey, cacheLayer.limits?.senderKey, cacheLayerExpiry.senderKey)
                 : rawSenderKey);
             const appStateStore = withAppStateLock(rawAppState);
             const messageStore = withMessageLock(rawMessages);
             const threadStore = withThreadLock(rawThreads);
             const contactStore = withContactLock(rawContacts);
             const privacyTokenStore = withPrivacyTokenLock(cacheLayer.privacyToken && usesBackend(providers.privacyToken)
-                ? withPrivacyTokenCache(rawPrivacyToken, cacheLayer.limits?.privacyToken)
+                ? withPrivacyTokenCache(rawPrivacyToken, cacheLayer.limits?.privacyToken, cacheLayerExpiry.privacyToken)
                 : rawPrivacyToken);
             let sessionDestroyed = false;
             let destroyPromise = null;

package/dist/esm/store/memory/identity.store.js

@@ -4,28 +4,52 @@ import { setBoundedMapEntry } from '../../util/collections.js';
 const DEFAULT_MAX_REMOTE_IDENTITIES = 8192;
 export class WaIdentityMemoryStore {
     constructor(options = {}) {
+        this.onEvict = (key) => this.onEntryRemove(key);
         this.remoteIdentities = new Map();
         this.maxRemoteIdentities = resolvePositive(options.maxRemoteIdentities, DEFAULT_MAX_REMOTE_IDENTITIES, 'WaIdentityMemoryStoreOptions.maxRemoteIdentities');
     }
     async getRemoteIdentity(address) {
-        return this.remoteIdentities.get(signalAddressKey(address)) ?? null;
+        const key = signalAddressKey(address);
+        const identityKey = this.remoteIdentities.get(key);
+        if (identityKey === undefined)
+            return null;
+        this.onEntryAccess(key);
+        return identityKey;
     }
     async getRemoteIdentities(addresses) {
         const result = new Array(addresses.length);
         for (let i = 0; i < addresses.length; i += 1) {
-            result[i] = this.remoteIdentities.get(signalAddressKey(addresses[i])) ?? null;
+            const key = signalAddressKey(addresses[i]);
+            const identityKey = this.remoteIdentities.get(key);
+            if (identityKey === undefined) {
+                result[i] = null;
+            }
+            else {
+                this.onEntryAccess(key);
+                result[i] = identityKey;
+            }
         }
         return result;
     }
     async setRemoteIdentity(address, identityKey) {
-        setBoundedMapEntry(this.remoteIdentities, signalAddressKey(address), identityKey, this.maxRemoteIdentities);
+        const key = signalAddressKey(address);
+        setBoundedMapEntry(this.remoteIdentities, key, identityKey, this.maxRemoteIdentities, this.onEvict);
+        this.onEntryAccess(key);
     }
     async setRemoteIdentities(entries) {
         for (const entry of entries) {
-            setBoundedMapEntry(this.remoteIdentities, signalAddressKey(entry.address), entry.identityKey, this.maxRemoteIdentities);
+            const key = signalAddressKey(entry.address);
+            setBoundedMapEntry(this.remoteIdentities, key, entry.identityKey, this.maxRemoteIdentities, this.onEvict);
+            this.onEntryAccess(key);
         }
     }
     async clear() {
         this.remoteIdentities.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 cap-evicted entry. */
+    onEntryRemove(key) { }
+    onEntriesClear() { }
 }

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

@@ -1,35 +1,52 @@
+import { resolvePositive } from '../../util/coercion.js';
 import { setBoundedMapEntry } from '../../util/collections.js';
 const DEFAULT_MAX_ENTRIES = 10000;
 export class WaPrivacyTokenMemoryStore {
-    constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    constructor(maxEntries) {
+        this.onEvict = (jid) => this.onEntryRemove(jid);
         this.records = new Map();
-        this.maxEntries = maxEntries;
+        this.maxEntries = 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;
-        setBoundedMapEntry(this.records, record.jid, merged, this.maxEntries);
+        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;
-            setBoundedMapEntry(this.records, record.jid, merged, this.maxEntries);
+            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/esm/store/memory/sender-key.store.js

@@ -7,20 +7,28 @@ const DEFAULT_SENDER_KEY_STORE_LIMITS = Object.freeze({
 });
 export 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 = resolvePositive(options.maxSenderKeys, DEFAULT_SENDER_KEY_STORE_LIMITS.senderKeys, 'WaSenderKeyMemoryStoreOptions.maxSenderKeys');
         this.maxSenderDistributions = resolvePositive(options.maxSenderDistributions, DEFAULT_SENDER_KEY_STORE_LIMITS.senderDistributions, 'WaSenderKeyMemoryStoreOptions.maxSenderDistributions');
     }
     async upsertSenderKey(record) {
-        setBoundedMapEntry(this.senderKeys, this.makeKey(record.groupId, record.sender), record, this.maxSenderKeys);
+        const key = this.makeKey(record.groupId, record.sender);
+        setBoundedMapEntry(this.senderKeys, key, record, this.maxSenderKeys, this.onSenderKeyEvict);
+        this.onEntryAccess(this.senderKeys, key);
     }
     async upsertSenderKeyDistribution(record) {
-        setBoundedMapEntry(this.senderDistributions, this.makeKey(record.groupId, record.sender), record, this.maxSenderDistributions);
+        const key = this.makeKey(record.groupId, record.sender);
+        setBoundedMapEntry(this.senderDistributions, key, record, this.maxSenderDistributions, this.onDistributionEvict);
+        this.onEntryAccess(this.senderDistributions, key);
     }
     async upsertSenderKeyDistributions(records) {
         for (const record of records) {
-            setBoundedMapEntry(this.senderDistributions, this.makeKey(record.groupId, record.sender), record, this.maxSenderDistributions);
+            const key = this.makeKey(record.groupId, record.sender);
+            setBoundedMapEntry(this.senderDistributions, key, record, this.maxSenderDistributions, this.onDistributionEvict);
+            this.onEntryAccess(this.senderDistributions, key);
         }
     }
     async getGroupSenderKeyList(groupId) {
@@ -42,14 +50,25 @@ export 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;
     }
@@ -71,7 +90,16 @@ export 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 = signalAddressKey(target);
@@ -80,6 +108,7 @@ export class SenderKeyMemoryStore {
             const sameAddress = signalAddressKey(record.sender) === targetAddressKey;
             if (sameGroup && sameAddress) {
                 map.delete(key);
+                this.onEntryRemove(map, key);
                 deleted += 1;
             }
         }

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

@@ -4,42 +4,76 @@ import { setBoundedMapEntry } from '../../util/collections.js';
 const DEFAULT_MAX_SESSIONS = 8192;
 export class WaSessionMemoryStore {
     constructor(options = {}) {
+        this.onEvict = (key) => this.onEntryRemove(key);
         this.signalSessions = new Map();
         this.maxSessions = resolvePositive(options.maxSessions, DEFAULT_MAX_SESSIONS, 'WaSessionMemoryStoreOptions.maxSessions');
     }
     async hasSession(address) {
-        return this.signalSessions.has(signalAddressKey(address));
+        const key = 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(signalAddressKey(addresses[i]));
+            const key = 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(signalAddressKey(address)) ?? null;
+        const key = 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(signalAddressKey(addresses[i])) ?? null;
+            const key = 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) {
-        setBoundedMapEntry(this.signalSessions, signalAddressKey(address), session, this.maxSessions);
+        const key = signalAddressKey(address);
+        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];
-            setBoundedMapEntry(this.signalSessions, signalAddressKey(entry.address), entry.session, this.maxSessions);
+            const key = signalAddressKey(entry.address);
+            setBoundedMapEntry(this.signalSessions, key, entry.session, this.maxSessions, this.onEvict);
+            this.onEntryAccess(key);
         }
     }
     async deleteSession(address) {
-        this.signalSessions.delete(signalAddressKey(address));
+        const key = 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() { }
 }

package/dist/esm/transport/node/WaMobileTcpSocket.js

@@ -1,13 +1,14 @@
 import { connect as netConnect } from 'node:net';
 import { WA_READY_STATES } from '../../protocol/constants.js';
-import { TEXT_ENCODER } from '../../util/bytes.js';
+import { toTcpProxyEndpoint } from '../proxy.js';
+import { concatBytes, TEXT_DECODER, TEXT_ENCODER } from '../../util/bytes.js';
 /**
  * `RawWebSocket`-shaped adapter over a raw Node TCP socket. Used by the
  * mobile transport to speak the WhatsApp Mobile binary protocol over
  * `tcp://host:port` URLs.
  */
 export class WaMobileTcpSocket {
-    constructor(url, _protocols, _options) {
+    constructor(url, _protocols, options) {
         this.binaryType = 'arraybuffer';
         this.readyState = WA_READY_STATES.CONNECTING;
         this.onopen = null;
@@ -19,19 +20,55 @@ export class WaMobileTcpSocket {
         this.closedClean = true;
         this.forceCloseTimer = null;
         const { host, port } = parseTcpUrl(url);
-        this.socket = netConnect({ host, port });
+        const proxy = toTcpProxyEndpoint(options?.agent);
+        this.socket = proxy
+            ? netConnect({ host: proxy.hostname, port: proxy.port })
+            : netConnect({ host, port });
+        let tunnelReady = !proxy;
+        let proxyResponse = new Uint8Array(0);
         this.socket.on('connect', () => {
             if (this.readyState !== WA_READY_STATES.CONNECTING)
                 return;
-            this.readyState = 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(TEXT_ENCODER.encode(`${lines.join('\r\n')}\r\n\r\n`));
+                return;
+            }
+            this.markOpen();
         });
         this.socket.on('data', (chunk) => {
-            if (!this.onmessage || this.readyState !== WA_READY_STATES.OPEN)
+            if (!tunnelReady && proxy) {
+                proxyResponse = 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 = 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;
@@ -53,6 +90,19 @@ export class WaMobileTcpSocket {
             });
         });
     }
+    markOpen() {
+        if (this.readyState !== WA_READY_STATES.CONNECTING)
+            return;
+        this.readyState = WA_READY_STATES.OPEN;
+        this.onopen?.({});
+    }
+    emitMessage(chunk) {
+        if (!this.onmessage || this.readyState !== WA_READY_STATES.OPEN)
+            return;
+        const copy = new Uint8Array(chunk.byteLength);
+        copy.set(chunk);
+        this.onmessage({ data: copy });
+    }
     send(data) {
         if (this.readyState !== WA_READY_STATES.OPEN) {
             throw new Error('WaMobileTcpSocket: send() called on non-OPEN socket');
@@ -85,6 +135,16 @@ export class WaMobileTcpSocket {
         this.forceCloseTimer.unref();
     }
 }
+/** 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/esm/transport/noise/WaMobileClientPayload.js

@@ -13,6 +13,20 @@ function parseAppVersion(version) {
         quaternary: at(3)
     };
 }
+function distributionChannelId(channel) {
+    const { DistributionChannel } = 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
@@ -24,14 +38,18 @@ export 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.ClientPayload.UserAgent.Platform.SMB_IOS
+            : proto.ClientPayload.UserAgent.Platform.IOS
+        : info.business
             ? proto.ClientPayload.UserAgent.Platform.SMB_ANDROID
-            : proto.ClientPayload.UserAgent.Platform.ANDROID,
+            : proto.ClientPayload.UserAgent.Platform.ANDROID;
+    const userAgent = {
+        platform,
         releaseChannel: proto.ClientPayload.UserAgent.ReleaseChannel.RELEASE,
         appVersion: version,
-        mcc: info.mcc ?? '000',
-        mnc: info.mnc ?? '000',
         osVersion: info.osVersion,
         manufacturer: info.manufacturer,
         device: info.device,
@@ -40,8 +58,10 @@ export function buildMobileLoginPayload(config) {
         localeLanguageIso6391: info.localeLanguageIso6391 ?? 'en',
         localeCountryIso31661Alpha2: info.localeCountryIso31661Alpha2 ?? 'US',
         deviceType: 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.ClientPayload.encode({
         passive: config.passive === true,

package/dist/esm/transport/proxy.js

@@ -1,3 +1,4 @@
+import { bytesToBase64, TEXT_ENCODER } from '../util/bytes.js';
 /** Type guard for an undici-style proxy dispatcher (has `dispatch` method). */
 export function isProxyDispatcher(value) {
     return (typeof value === 'object' &&
@@ -30,3 +31,85 @@ export function toProxyAgent(proxy) {
     }
     return proxy;
 }
+const TCP_PROXY_HINT = 'socketOptions.proxy.ws must hold an http.Agent-style proxy pointing at an http: url (e.g. new HttpProxyAgent("http://host:port")) to tunnel raw TCP';
+/**
+ * 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 function toTcpProxyEndpoint(proxy) {
+    if (!proxy) {
+        return undefined;
+    }
+    if (!isProxyAgent(proxy)) {
+        if (isProxyDispatcher(proxy)) {
+            throw new Error(`undici-style proxy dispatchers cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+        }
+        throw new Error(`unsupported proxy transport – ${TCP_PROXY_HINT}`);
+    }
+    const url = readAgentProxyUrl(proxy);
+    if (url.protocol !== 'http:') {
+        throw new Error(`proxy protocol ${url.protocol} is not supported by the raw TCP tunnel – ${TCP_PROXY_HINT}`);
+    }
+    const username = decodeProxyUserInfo(url.username, 'username');
+    const password = decodeProxyUserInfo(url.password, 'password');
+    return {
+        hostname: url.hostname,
+        port: url.port ? Number(url.port) : 80,
+        authorization: username || password
+            ? `Basic ${bytesToBase64(TEXT_ENCODER.encode(`${username}:${password}`))}`
+            : undefined
+    };
+}
+/** Throws when {@link toTcpProxyEndpoint} cannot honour `proxy`. */
+export function assertTcpProxySupported(proxy) {
+    toTcpProxyEndpoint(proxy);
+}
+/**
+ * Decodes one userinfo component of a proxy url. `new URL()` keeps invalid
+ * percent escapes verbatim, so a credential holding a literal `%` would reach
+ * `decodeURIComponent` and throw a bare `URIError`. The value never reaches the
+ * message – only the field name does.
+ */
+function decodeProxyUserInfo(value, field) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new Error(`proxy url ${field} contains a malformed percent escape`);
+    }
+}
+/**
+ * Reads the proxy url an `http.Agent`-style proxy exposes. Every `*-proxy-agent`
+ * package keeps it on `.proxy`, but only the http/https ones store a `URL`
+ * there – `socks-proxy-agent` stores a parsed `{ host, port, type }` endpoint.
+ */
+function readAgentProxyUrl(agent) {
+    const value = agent.proxy;
+    if (value instanceof URL) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            return new URL(value);
+        }
+        catch {
+            throw new Error(`proxy agent exposes an unparseable proxy url ${JSON.stringify(value)}`);
+        }
+    }
+    if (isSocksProxyEndpoint(value)) {
+        throw new Error(`socks proxy agents cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+    }
+    throw new Error(`proxy agent exposes no proxy url – ${TCP_PROXY_HINT}`);
+}
+/** Matches the `{ host, port, type }` endpoint `socks-proxy-agent` keeps on `.proxy`. */
+function isSocksProxyEndpoint(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.host === 'string' &&
+        typeof value.port === 'number');
+}