@ikyyjee/ikyysinggle 1.7.7

package/lib/Utils/meta-ai-msmsg.js

@@ -0,0 +1,271 @@
+/**
+ * lib/Utils/meta-ai-msmsg.js — decrypts the "msmsg" message envelope used
+ * when a bot (e.g. Meta AI in a chat/group) sends a response. This envelope
+ * is encrypted differently from normal 1:1/group messages (it's keyed off
+ * a `messageSecret` your own earlier message carried, not the usual Signal
+ * session), so it needs its own decrypt path — see decode-wa-message.js's
+ * `case 'msmsg':` for where this gets called from.
+ *
+ * Ported (CommonJS -> ES modules only, logic unchanged) from a sibling
+ * fork; wired in here because the previous behavior was to silently drop
+ * every incoming msmsg message instead of decrypting it (see the removed
+ * "TODO: temporary fix" block in messages-recv.js's handleMessage).
+ */
+import { aesDecryptGCM } from './crypto.js';
+import { proto } from '../../WAProto/index.js';
+import nodeCrypto from 'crypto';
+
+// crypto.js's `hkdf` re-export (backed by the optional whatsapp-rust-bridge
+// native addon) only accepts a *string* for its `info` option. msmsg
+// decryption needs raw-byte `info`/`aad` (concatenated id + jid bytes), so
+// this file uses its own small, standard RFC 5869 HKDF-HMAC-SHA256
+// implementation instead — self-contained, doesn't touch or replace the
+// native hkdf used anywhere else in the codebase.
+const hkdfExtractJS = (salt, ikm) => nodeCrypto.createHmac('sha256', salt).update(ikm).digest();
+const hkdfExpandJS = (prk, length, info) => {
+    const hashLen = 32;
+    const n = Math.ceil(length / hashLen);
+    let t = Buffer.alloc(0);
+    let okm = Buffer.alloc(0);
+    for (let i = 1; i <= n; i++) {
+        t = nodeCrypto.createHmac('sha256', prk).update(Buffer.concat([t, info, Buffer.from([i])])).digest();
+        okm = Buffer.concat([okm, t]);
+    }
+    return okm.subarray(0, length);
+};
+const hkdf = (ikm, length, options = {}) => {
+    const ikmBuf = Buffer.isBuffer(ikm) ? ikm : Buffer.from(ikm);
+    const saltBuf = options.salt ? (Buffer.isBuffer(options.salt) ? options.salt : Buffer.from(options.salt)) : Buffer.alloc(32);
+    const infoBuf = options.info ? (Buffer.isBuffer(options.info) ? options.info : Buffer.from(options.info)) : Buffer.alloc(0);
+    const prk = hkdfExtractJS(saltBuf, ikmBuf);
+    return hkdfExpandJS(prk, length, infoBuf);
+};
+
+const BOT_MESSAGE_INFO = 'Bot Message';
+const KEY_LENGTH = 32;
+const AUTH_TAG_LENGTH = 16;
+const MSG_ID_HEX_RE = /^[0-9A-Fa-f]{32}$/;
+
+const unpadRandomMax16 = (value) => {
+    const bytes = new Uint8Array(value);
+    if (!bytes.length) {
+        throw new Error('unpadPkcs7 given empty bytes');
+    }
+    const padLength = bytes[bytes.length - 1];
+    if (padLength > bytes.length) {
+        throw new Error(`unpad given ${bytes.length} bytes, but pad is ${padLength}`);
+    }
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.length - padLength);
+};
+
+const toBuffer = (value) => {
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    }
+    return Buffer.from(value);
+};
+
+const normalizeLidJid = (jid) => {
+    if (!jid || !jid.endsWith('@lid') || !jid.includes(':')) {
+        return jid;
+    }
+    return `${jid.split(':')[0]}@lid`;
+};
+
+const buildMessageIdRepresentations = (messageId) => {
+    const ascii = Buffer.from(messageId);
+    const binary = MSG_ID_HEX_RE.test(messageId) ? Buffer.from(messageId, 'hex') : ascii;
+    return [
+        { label: 'msgIdAscii', value: ascii },
+        ...(binary.equals(ascii) ? [] : [{ label: 'msgIdBinary', value: binary }])
+    ];
+};
+
+const pushUnique = (items, seen, item) => {
+    const key = JSON.stringify([
+        item.messageId,
+        item.idSource,
+        item.idSources,
+        item.infoSource,
+        item.aadSource,
+        item.info.toString('hex'),
+        item.aad.toString('hex')
+    ]);
+    if (!seen.has(key)) {
+        seen.add(key);
+        items.push(item);
+    }
+};
+
+const getCandidateIds = (messageKey) => {
+    const orderedCandidates = [
+        messageKey?.botType === 'full'
+            ? { source: 'stanzaId', messageId: messageKey?.stanzaId }
+            : { source: 'botEditTargetId', messageId: messageKey?.botEditTargetId },
+        { source: 'targetId', messageId: messageKey?.targetId },
+        { source: 'metaTargetId', messageId: messageKey?.metaTargetId },
+        { source: 'stanzaId', messageId: messageKey?.stanzaId }
+    ];
+    const targetIdCandidates = Array.isArray(messageKey?.targetIdCandidates) ? messageKey.targetIdCandidates : [];
+    for (let index = 0; index < targetIdCandidates.length; index += 1) {
+        orderedCandidates.push({
+            source: `targetIdCandidates[${index}]`,
+            messageId: targetIdCandidates[index]
+        });
+    }
+    const grouped = new Map();
+    for (const candidate of orderedCandidates) {
+        if (!candidate.messageId) {
+            continue;
+        }
+        const messageId = String(candidate.messageId);
+        const existing = grouped.get(messageId);
+        if (existing) {
+            if (!existing.idSources.includes(candidate.source)) {
+                existing.idSources.push(candidate.source);
+            }
+        }
+        else {
+            grouped.set(messageId, {
+                messageId,
+                idSource: candidate.source,
+                idSources: [candidate.source]
+            });
+        }
+    }
+    return Array.from(grouped.values());
+};
+
+const getJidCandidates = (messageKey) => {
+    const ordered = [
+        { source: 'meId', jid: messageKey?.meId },
+        { source: 'conversationJid', jid: messageKey?.conversationJid },
+        { source: 'senderJid', jid: messageKey?.senderJid },
+        { source: 'meLidNormalized', jid: normalizeLidJid(messageKey?.meLid) }
+    ];
+    const seen = new Set();
+    const candidates = [];
+    for (const candidate of ordered) {
+        if (!candidate.jid) {
+            continue;
+        }
+        const jid = String(candidate.jid);
+        if (!seen.has(jid)) {
+            seen.add(jid);
+            candidates.push({ source: candidate.source, jid, value: Buffer.from(jid) });
+        }
+    }
+    return candidates;
+};
+
+const buildMsmsgDecryptionStrategies = (messageKey) => {
+    const botJid = String(messageKey?.participant || '');
+    const botJidBuffer = Buffer.from(botJid);
+    const targetIds = getCandidateIds(messageKey);
+    const jidCandidates = getJidCandidates(messageKey);
+    const primaryJid = jidCandidates[0];
+    const alternateJid = jidCandidates.find((candidate) => candidate.source !== primaryJid?.source && candidate.jid !== botJid);
+    const strategies = [];
+    const seen = new Set();
+    for (const idCandidate of targetIds) {
+        const idForms = buildMessageIdRepresentations(idCandidate.messageId);
+        for (const idForm of idForms) {
+            pushUnique(strategies, seen, {
+                mode: '2step',
+                idSource: idCandidate.idSource,
+                idSources: idCandidate.idSources,
+                infoSource: `${idForm.label}+meId+botJid`,
+                aadSource: `${idForm.label}+0+botJid`,
+                authTagLayout: 'trailing',
+                messageId: idCandidate.messageId,
+                info: Buffer.concat([idForm.value, primaryJid.value, botJidBuffer, Buffer.alloc(0)]),
+                aad: Buffer.concat([idForm.value, Buffer.from([0]), botJidBuffer]),
+                attemptLabel: `${idCandidate.idSource}:${idForm.label}:primary`
+            });
+            if (alternateJid) {
+                pushUnique(strategies, seen, {
+                    mode: '2step',
+                    idSource: idCandidate.idSource,
+                    idSources: idCandidate.idSources,
+                    infoSource: `${idForm.label}+${alternateJid.source}+botJid`,
+                    aadSource: `${idForm.label}+0+${alternateJid.source}`,
+                    authTagLayout: 'trailing',
+                    messageId: idCandidate.messageId,
+                    info: Buffer.concat([idForm.value, alternateJid.value, botJidBuffer, Buffer.alloc(0)]),
+                    aad: Buffer.concat([idForm.value, Buffer.from([0]), alternateJid.value]),
+                    attemptLabel: `${idCandidate.idSource}:${idForm.label}:${alternateJid.source}`
+                });
+            }
+        }
+    }
+    return strategies.slice(0, 12);
+};
+
+const assertRequired = (value, label) => {
+    if (!value ||
+        (Buffer.isBuffer(value) && value.length === 0) ||
+        (value instanceof Uint8Array && value.byteLength === 0)) {
+        throw new Error(`Missing required ${label} for msmsg decryption`);
+    }
+};
+
+const decryptWithStrategy = (messageSecret, msMsg, strategy) => {
+    const baseSecret = Buffer.from(hkdf(toBuffer(messageSecret), KEY_LENGTH, { info: BOT_MESSAGE_INFO }));
+    const key = Buffer.from(hkdf(baseSecret, KEY_LENGTH, { info: strategy.info }));
+    const payload = toBuffer(msMsg.encPayload);
+    const ciphertextWithTag = Buffer.concat([payload.slice(0, -AUTH_TAG_LENGTH), payload.slice(-AUTH_TAG_LENGTH)]);
+    return Buffer.from(aesDecryptGCM(ciphertextWithTag, key, toBuffer(msMsg.encIv), strategy.aad));
+};
+
+export const decodeDecryptedMsmsgMessage = (decrypted) => {
+    const messageBuffer = toBuffer(decrypted);
+    try {
+        const unpadded = Buffer.from(unpadRandomMax16(messageBuffer));
+        const decoded = proto.Message.decode(unpadded);
+        const hasContent = Object.keys(decoded).some((key) => key !== 'messageContextInfo' && decoded[key] != null);
+        if (hasContent) {
+            return decoded;
+        }
+    }
+    catch {
+        // fall through to decoding the raw buffer below
+    }
+    return proto.Message.decode(messageBuffer);
+};
+
+export const decryptMsmsgBotMessage = async (messageSecret, messageKey, msMsg) => {
+    assertRequired(messageSecret, 'messageSecret');
+    assertRequired(messageKey?.participant, 'participant');
+    assertRequired(messageKey?.meId, 'meId');
+    assertRequired(msMsg?.encIv, 'encIv');
+    assertRequired(msMsg?.encPayload, 'encPayload');
+    if (getCandidateIds(messageKey).length === 0) {
+        throw new Error('Missing required target message id for msmsg decryption');
+    }
+    const strategies = buildMsmsgDecryptionStrategies(messageKey);
+    const attemptedStrategies = [];
+    let lastError;
+    for (const strategy of strategies) {
+        const attempt = {
+            idSource: strategy.idSource,
+            idSources: strategy.idSources,
+            infoSource: strategy.infoSource,
+            aadSource: strategy.aadSource,
+            messageId: strategy.messageId
+        };
+        try {
+            return await decryptWithStrategy(messageSecret, msMsg, strategy);
+        }
+        catch (error) {
+            attemptedStrategies.push(attempt);
+            lastError = error;
+        }
+    }
+    const error = new Error('Failed to decrypt msmsg with bounded deterministic strategies');
+    error.attemptedStrategies = attemptedStrategies;
+    error.cause = lastError;
+    throw error;
+};

package/lib/Utils/native-bridge.js

@@ -0,0 +1,77 @@
+/**
+ * lib/Utils/native-bridge.js — best-effort loader for the optional
+ * `whatsapp-rust-bridge` native addon. If it isn't installed (it's an
+ * optional dependency), every function here just returns null instead of
+ * throwing, so nothing breaks for people who don't need it.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const BRIDGE_NAME = 'whatsapp-rust-bridge';
+let cached;
+let attempted = false;
+
+const findPackageDir = (pkgName) => {
+    let searchPaths;
+    try {
+        searchPaths = require.resolve.paths(pkgName) || [];
+    }
+    catch {
+        searchPaths = [];
+    }
+    for (const dir of searchPaths) {
+        const candidate = path.join(dir, pkgName);
+        if (fs.existsSync(path.join(candidate, 'package.json'))) {
+            return candidate;
+        }
+    }
+    return null;
+};
+
+export const loadRustBridge = () => {
+    if (attempted) {
+        return cached;
+    }
+    attempted = true;
+    try {
+        cached = require(BRIDGE_NAME);
+        return cached;
+    }
+    catch (error) {
+        const recoverableCodes = new Set(['ERR_PACKAGE_PATH_NOT_EXPORTED', 'ERR_PACKAGE_IMPORT_NOT_DEFINED']);
+        if (!recoverableCodes.has(error?.code)) {
+            cached = null;
+            return null;
+        }
+        try {
+            const dir = findPackageDir(BRIDGE_NAME);
+            if (!dir) {
+                cached = null;
+                return null;
+            }
+            const pkgJson = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+            const candidates = [
+                pkgJson.main,
+                'index.js',
+                'index.node',
+                'dist/index.js',
+                'lib/index.js',
+                'build/index.js'
+            ].filter(Boolean);
+            for (const rel of candidates) {
+                const fullPath = path.join(dir, rel);
+                if (fs.existsSync(fullPath)) {
+                    cached = require(fullPath);
+                    return cached;
+                }
+            }
+        }
+        catch {
+            // fall through to returning null below
+        }
+        cached = null;
+        return null;
+    }
+};

package/lib/Utils/noise-handler.js

@@ -0,0 +1,201 @@
+import { Boom } from '@hapi/boom';
+import { proto } from '../../WAProto/index.js';
+import { NOISE_MODE, WA_CERT_DETAILS } from '../Defaults/index.js';
+import { decodeBinaryNode } from '../WABinary/index.js';
+import { aesDecryptGCM, aesEncryptGCM, Curve, hkdf, sha256 } from './crypto.js';
+const IV_LENGTH = 12;
+const EMPTY_BUFFER = Buffer.alloc(0);
+const generateIV = (counter) => {
+    const iv = new ArrayBuffer(IV_LENGTH);
+    new DataView(iv).setUint32(8, counter);
+    return new Uint8Array(iv);
+};
+class TransportState {
+    constructor(encKey, decKey) {
+        this.encKey = encKey;
+        this.decKey = decKey;
+        this.readCounter = 0;
+        this.writeCounter = 0;
+        this.iv = new Uint8Array(IV_LENGTH);
+    }
+    encrypt(plaintext) {
+        const c = this.writeCounter++;
+        this.iv[8] = (c >>> 24) & 0xff;
+        this.iv[9] = (c >>> 16) & 0xff;
+        this.iv[10] = (c >>> 8) & 0xff;
+        this.iv[11] = c & 0xff;
+        return aesEncryptGCM(plaintext, this.encKey, this.iv, EMPTY_BUFFER);
+    }
+    decrypt(ciphertext) {
+        const c = this.readCounter++;
+        this.iv[8] = (c >>> 24) & 0xff;
+        this.iv[9] = (c >>> 16) & 0xff;
+        this.iv[10] = (c >>> 8) & 0xff;
+        this.iv[11] = c & 0xff;
+        return aesDecryptGCM(ciphertext, this.decKey, this.iv, EMPTY_BUFFER);
+    }
+}
+export const makeNoiseHandler = ({ keyPair: { private: privateKey, public: publicKey }, NOISE_HEADER, logger, routingInfo }) => {
+    logger = logger.child({ class: 'ns' });
+    const data = Buffer.from(NOISE_MODE);
+    let hash = data.byteLength === 32 ? data : sha256(data);
+    let salt = hash;
+    let encKey = hash;
+    let decKey = hash;
+    let counter = 0;
+    let sentIntro = false;
+    let inBytes = Buffer.alloc(0);
+    let transport = null;
+    let isWaitingForTransport = false;
+    let pendingOnFrame = null;
+    let introHeader;
+    if (routingInfo) {
+        introHeader = Buffer.alloc(7 + routingInfo.byteLength + NOISE_HEADER.length);
+        introHeader.write('ED', 0, 'utf8');
+        introHeader.writeUint8(0, 2);
+        introHeader.writeUint8(1, 3);
+        introHeader.writeUint8(routingInfo.byteLength >> 16, 4);
+        introHeader.writeUint16BE(routingInfo.byteLength & 65535, 5);
+        introHeader.set(routingInfo, 7);
+        introHeader.set(NOISE_HEADER, 7 + routingInfo.byteLength);
+    }
+    else {
+        introHeader = Buffer.from(NOISE_HEADER);
+    }
+    const authenticate = (data) => {
+        if (!transport) {
+            hash = sha256(Buffer.concat([hash, data]));
+        }
+    };
+    const encrypt = (plaintext) => {
+        if (transport) {
+            return transport.encrypt(plaintext);
+        }
+        const result = aesEncryptGCM(plaintext, encKey, generateIV(counter++), hash);
+        authenticate(result);
+        return result;
+    };
+    const decrypt = (ciphertext) => {
+        if (transport) {
+            return transport.decrypt(ciphertext);
+        }
+        const result = aesDecryptGCM(ciphertext, decKey, generateIV(counter++), hash);
+        authenticate(ciphertext);
+        return result;
+    };
+    const localHKDF = (data) => {
+        const key = hkdf(Buffer.from(data), 64, { salt, info: '' });
+        return [key.subarray(0, 32), key.subarray(32)];
+    };
+    const mixIntoKey = (data) => {
+        const [write, read] = localHKDF(data);
+        salt = write;
+        encKey = read;
+        decKey = read;
+        counter = 0;
+    };
+    const finishInit = async () => {
+        isWaitingForTransport = true;
+        const [write, read] = localHKDF(new Uint8Array(0));
+        transport = new TransportState(write, read);
+        isWaitingForTransport = false;
+        logger.trace('Noise handler transitioned to Transport state');
+        if (pendingOnFrame) {
+            logger.trace({ length: inBytes.length }, 'Flushing buffered frames after transport ready');
+            await processData(pendingOnFrame);
+            pendingOnFrame = null;
+        }
+    };
+    const processData = async (onFrame) => {
+        let size;
+        while (true) {
+            if (inBytes.length < 3)
+                return;
+            size = (inBytes[0] << 16) | (inBytes[1] << 8) | inBytes[2];
+            if (inBytes.length < size + 3)
+                return;
+            let frame = inBytes.subarray(3, size + 3);
+            inBytes = inBytes.subarray(size + 3);
+            if (transport) {
+                const result = transport.decrypt(frame);
+                frame = await decodeBinaryNode(result);
+            }
+            if (logger.level === 'trace') {
+                logger.trace({ msg: frame?.attrs?.id }, 'recv frame');
+            }
+            onFrame(frame);
+        }
+    };
+    authenticate(NOISE_HEADER);
+    authenticate(publicKey);
+    return {
+        encrypt,
+        decrypt,
+        authenticate,
+        mixIntoKey,
+        finishInit,
+        processHandshake: ({ serverHello }, noiseKey) => {
+            authenticate(serverHello.ephemeral);
+            mixIntoKey(Curve.sharedKey(privateKey, serverHello.ephemeral));
+            const decStaticContent = decrypt(serverHello.static);
+            mixIntoKey(Curve.sharedKey(privateKey, decStaticContent));
+            const certDecoded = decrypt(serverHello.payload);
+            const { intermediate: certIntermediate, leaf } = proto.CertChain.decode(certDecoded);
+            // leaf
+            if (!leaf?.details || !leaf?.signature) {
+                throw new Boom('invalid noise leaf certificate', { statusCode: 400 });
+            }
+            if (!certIntermediate?.details || !certIntermediate?.signature) {
+                throw new Boom('invalid noise intermediate certificate', { statusCode: 400 });
+            }
+            const details = proto.CertChain.NoiseCertificate.Details.decode(certIntermediate.details);
+            const { issuerSerial } = details;
+            const verify = Curve.verify(details.key, leaf.details, leaf.signature);
+            const verifyIntermediate = Curve.verify(WA_CERT_DETAILS.PUBLIC_KEY, certIntermediate.details, certIntermediate.signature);
+            if (!verify) {
+                throw new Boom('noise certificate signature invalid', { statusCode: 400 });
+            }
+            if (!verifyIntermediate) {
+                throw new Boom('noise intermediate certificate signature invalid', { statusCode: 400 });
+            }
+            if (issuerSerial !== WA_CERT_DETAILS.SERIAL) {
+                throw new Boom('certification match failed', { statusCode: 400 });
+            }
+            const keyEnc = encrypt(noiseKey.public);
+            mixIntoKey(Curve.sharedKey(noiseKey.private, serverHello.ephemeral));
+            return keyEnc;
+        },
+        encodeFrame: (data) => {
+            if (transport) {
+                data = transport.encrypt(data);
+            }
+            const dataLen = data.byteLength;
+            const introSize = sentIntro ? 0 : introHeader.length;
+            const frame = Buffer.allocUnsafe(introSize + 3 + dataLen);
+            if (!sentIntro) {
+                frame.set(introHeader);
+                sentIntro = true;
+            }
+            frame[introSize] = (dataLen >>> 16) & 0xff;
+            frame[introSize + 1] = (dataLen >>> 8) & 0xff;
+            frame[introSize + 2] = dataLen & 0xff;
+            frame.set(data, introSize + 3);
+            return frame;
+        },
+        decodeFrame: async (newData, onFrame) => {
+            if (isWaitingForTransport) {
+                inBytes = Buffer.concat([inBytes, newData]);
+                pendingOnFrame = onFrame;
+                return;
+            }
+            if (inBytes.length === 0) {
+                inBytes = Buffer.from(newData);
+            }
+            else {
+                inBytes = Buffer.concat([inBytes, newData]);
+            }
+            await processData(onFrame);
+        }
+    };
+};
+//# sourceMappingURL=noise-handler.js.map

package/lib/Utils/offline-node-processor.js

@@ -0,0 +1,40 @@
+/**
+ * Creates a processor for offline stanza nodes that:
+ * - Queues nodes for sequential processing
+ * - Yields to the event loop periodically to avoid blocking
+ * - Catches handler errors to prevent the processing loop from crashing
+ */
+export function makeOfflineNodeProcessor(nodeProcessorMap, deps, batchSize = 10) {
+    const nodes = [];
+    let isProcessing = false;
+    const enqueue = (type, node) => {
+        nodes.push({ type, node });
+        if (isProcessing) {
+            return;
+        }
+        isProcessing = true;
+        const promise = async () => {
+            let processedInBatch = 0;
+            while (nodes.length && deps.isWsOpen()) {
+                const { type, node } = nodes.shift();
+                const nodeProcessor = nodeProcessorMap.get(type);
+                if (!nodeProcessor) {
+                    deps.onUnexpectedError(new Error(`unknown offline node type: ${type}`), 'processing offline node');
+                    continue;
+                }
+                await nodeProcessor(node).catch(err => deps.onUnexpectedError(err, `processing offline ${type}`));
+                processedInBatch++;
+                // Yield to event loop after processing a batch
+                // This prevents blocking the event loop for too long when there are many offline nodes
+                if (processedInBatch >= batchSize) {
+                    processedInBatch = 0;
+                    await deps.yieldToEventLoop();
+                }
+            }
+            isProcessing = false;
+        };
+        promise().catch(error => deps.onUnexpectedError(error, 'processing offline nodes'));
+    };
+    return { enqueue };
+}
+//# sourceMappingURL=offline-node-processor.js.map

package/lib/Utils/optimizer.js

@@ -0,0 +1,90 @@
+/**
+ * lib/Utils/optimizer.js — opt-in resource-usage tuning ("optiMazer").
+ *
+ * OFF by default. This does NOT touch the safety caps that already exist
+ * unconditionally elsewhere (userDevicesCache, message-retry caches, and
+ * the guard log arrays all have sane hard limits regardless of this
+ * setting — those are bug fixes, not something you should be able to turn
+ * off). What `optiMazer` adds on top, only when enabled, is:
+ *
+ *  - Tighter cache limits than the defaults (trades a little more
+ *    re-fetching on cache misses for meaningfully less resident memory on
+ *    a long-running, high-traffic process).
+ *  - A periodic background trim/stats tick.
+ *  - If Node was started with `--expose-gc`, a periodic proactive GC pass
+ *    during that same tick (a safe no-op if `--expose-gc` wasn't used).
+ *
+ * It never changes protocol behavior, message content, or connection
+ * behavior — purely memory bookkeeping. See README.md → "optiMazer".
+ */
+
+export const DEFAULT_OPTIMIZER_CONFIG = {
+    userDevicesCacheMaxKeys: 2000, // vs the always-on default of 10000
+    retryCountersMax: 1500, // vs the always-on default of 5000
+    sessionRecreateHistoryMax: 500, // vs the always-on default of 2000
+    guardLogMax: 50, // vs the always-on default of 200
+    gcIntervalMs: 5 * 60 * 1000, // only used if the process was started with --expose-gc
+    tickIntervalMs: 60 * 1000
+};
+
+/** Merge whatever the caller passed (boolean or partial config object) with the defaults above. */
+export const resolveOptimizerConfig = (optiMazer) => {
+    if (!optiMazer) {
+        return null;
+    }
+    const overrides = typeof optiMazer === 'object' ? optiMazer : {};
+    return { ...DEFAULT_OPTIMIZER_CONFIG, ...overrides };
+};
+
+export class OptiMazer {
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_OPTIMIZER_CONFIG, ...config };
+        this.stats = { ticks: 0, gcRuns: 0, startedAt: Date.now() };
+        this._timers = [];
+    }
+
+    /** Call once after building your socket. Safe to call multiple times (no-op if already attached). */
+    attach(sock) {
+        if (this._attached) {
+            return this;
+        }
+        this._attached = true;
+        const tick = () => {
+            this.stats.ticks++;
+            if (typeof global.gc === 'function') {
+                try {
+                    global.gc();
+                    this.stats.gcRuns++;
+                }
+                catch {
+                    // --expose-gc wasn't actually set up correctly; just skip silently
+                }
+            }
+        };
+        const timer = setInterval(tick, this.config.tickIntervalMs);
+        timer.unref?.();
+        this._timers.push(timer);
+        this._sock = sock;
+        return this;
+    }
+
+    getStats() {
+        return {
+            ...this.stats,
+            uptimeMs: Date.now() - this.stats.startedAt,
+            gcAvailable: typeof global.gc === 'function',
+            memory: process.memoryUsage()
+        };
+    }
+
+    stop() {
+        for (const t of this._timers) {
+            clearInterval(t);
+        }
+        this._timers = [];
+        this._attached = false;
+    }
+}
+
+/** Convenience factory so you can also do `import { optiMazer } from '@xayz/baileys'`. */
+export const optiMazer = (config) => new OptiMazer(config);