plogme 1.0.0

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

@@ -0,0 +1,130 @@
+import { proto } from '../../WAProto/index.js';
+import { aesDecryptGCM, hkdf } from './crypto.js';
+
+const BOT_MESSAGE_INFO = 'Bot Message';
+const KEY_LENGTH = 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);
+};
+
+// Strips device suffix from LID JIDs: "user:device@lid" → "user@lid".
+// jidEncode includes ":0" even for device=0 (user/non-AD form), so normalize both meId and meLid.
+const normalizeLidJid = (jid) => {
+    if (!jid || !jid.endsWith('@lid') || !jid.includes(':')) return jid;
+    return `${jid.split(':')[0]}@lid`;
+};
+
+// Ordered msgId candidates per the Rust BotMessageContext:
+//   botEditTargetId when editing, stanzaId for the normal full response, metaTargetId as fallback.
+const selectMsgIdCandidates = (messageKey) => {
+    const seen = new Set();
+    const result = [];
+    for (const id of [messageKey?.botEditTargetId, messageKey?.stanzaId, messageKey?.metaTargetId]) {
+        const s = id ? String(id) : '';
+        if (s && !seen.has(s)) {
+            seen.add(s);
+            result.push(s);
+        }
+    }
+    return result;
+};
+
+// Ordered target_sender_user_jid candidates per Rust spec (non-AD user JID = no device suffix).
+// jidEncode produces "user:0@lid" for device=0 LID JIDs, so normalize both meId and meLid.
+const selectTargetJidCandidates = (messageKey) => {
+    const seen = new Set();
+    const result = [];
+    for (const jid of [normalizeLidJid(messageKey?.meId), normalizeLidJid(messageKey?.meLid)]) {
+        const s = jid ? String(jid) : '';
+        if (s && !seen.has(s)) {
+            seen.add(s);
+            result.push(s);
+        }
+    }
+    return result;
+};
+
+const decodeDecryptedMsmsgMessage = (decrypted) => {
+    const buf = toBuffer(decrypted);
+    try {
+        const unpadded = Buffer.from(unpadRandomMax16(buf));
+        const decoded = proto.Message.decode(unpadded);
+        const hasContent = Object.keys(decoded).some(k => k !== 'messageContextInfo' && decoded[k] != null);
+        if (hasContent) return decoded;
+    }
+    catch {}
+    return proto.Message.decode(buf);
+};
+
+/**
+ * Decrypts <enc type="msmsg"> bot messages.
+ *
+ * Two-pass HKDF — algorithm from bot_message.rs (BotMessageContext):
+ *   k1    = HKDF(messageSecret, salt=∅, info="Bot Message",                     32)
+ *   k2    = HKDF(k1,            salt=∅, info=msgID||target_sender_jid||bot_jid, 32)
+ *   AAD   = msgID || 0x00 || bot_user_jid
+ *   plain = AES-256-GCM.Decrypt(k2, encIv, encPayload, AAD)
+ *
+ * k1 is shared across all candidates and derived once.
+ * AAD always uses bot_user_jid, never target_sender_jid.
+ */
+export const decryptMsmsgBotMessage = async (messageSecret, messageKey, msMsg) => {
+    if (!messageSecret || (messageSecret instanceof Uint8Array && !messageSecret.byteLength)) {
+        throw new Error('Missing required messageSecret for msmsg decryption');
+    }
+    if (!messageKey?.participant) throw new Error('Missing required participant for msmsg decryption');
+    if (!messageKey?.meId) throw new Error('Missing required meId for msmsg decryption');
+    if (!msMsg?.encIv) throw new Error('Missing required encIv for msmsg decryption');
+    if (!msMsg?.encPayload) throw new Error('Missing required encPayload for msmsg decryption');
+
+    const msgIdCandidates = selectMsgIdCandidates(messageKey);
+    if (!msgIdCandidates.length) throw new Error('Missing required target message id for msmsg decryption');
+
+    const targetJidCandidates = selectTargetJidCandidates(messageKey);
+    if (!targetJidCandidates.length) throw new Error('Missing required target JID for msmsg decryption');
+
+    const botJidBuf = Buffer.from(String(messageKey.participant));
+    const payload = toBuffer(msMsg.encPayload);
+    const iv = toBuffer(msMsg.encIv);
+
+    // k1 depends only on messageSecret — derive once and reuse across all candidates
+    const baseKey = Buffer.from(hkdf(toBuffer(messageSecret), KEY_LENGTH, { info: BOT_MESSAGE_INFO }));
+
+    let lastError;
+    for (const msgId of msgIdCandidates) {
+        // msg_id is always passed as ASCII bytes per Rust spec (msg_id.as_bytes())
+        const idBuf = Buffer.from(msgId);
+        for (const targetJid of targetJidCandidates) {
+            const info = Buffer.concat([idBuf, Buffer.from(targetJid), botJidBuf]);
+            const key = Buffer.from(hkdf(baseKey, KEY_LENGTH, { info }));
+            const aad = Buffer.concat([idBuf, Buffer.from([0x00]), botJidBuf]);
+            try {
+                return Buffer.from(aesDecryptGCM(payload, key, iv, aad));
+            }
+            catch (e) {
+                lastError = e;
+            }
+        }
+    }
+
+    const err = new Error('msmsg decryption failed: all key derivation candidates exhausted');
+    err.cause = lastError;
+    throw err;
+};
+
+export { decodeDecryptedMsmsgMessage };

package/lib/Utils/meta-compositing.js

@@ -0,0 +1,202 @@
+/**
+ * Lia@Changes [WIP]
+ * Meta Compositing — send rich messages with Meta AI-style progress indicator.
+ *
+ * UNIVERSAL VERSION: Works on ALL WhatsApp clients.
+ *   - Native Meta AI rendering is opt-in and requires caller-supplied verification metadata
+ *   - Plain text fallback is used unless the native payload can be authenticated
+ *
+ * metaTyping() — shows the "typing..." / planning steps indicator.
+ * sendMetaComposited() — full flow: typing → delete → final message.
+ *
+ * If you use or copy this code, please credit @crysnovax/bailey.
+ */
+
+import { proto } from '../../WAProto/index.js';
+import { BOT_RENDERING_CONFIG_METADATA } from '../Defaults/index.js';
+import { premiumEnabled } from './integrity.js';
+import { delay } from './generics.js';
+
+// ─── Step status enum ───
+export const PlanningStepStatus = {
+    IN_PROGRESS: 0,
+    DONE: 1,
+    FAILED: 2
+};
+
+/**
+ * Check whether the socket explicitly allows native Meta AI progress rendering.
+ * WhatsApp validates bot verification metadata on these messages. The library
+ * therefore refuses to fabricate certificates or signatures: native rendering
+ * requires both an explicit socket opt-in and verification metadata obtained from
+ * a compatible, trusted Meta AI message/session.
+ */
+export const supportsMetaRendering = (_jid, config = {}) => {
+    return config.forceMetaRendering === true &&
+        config.metaAiRendering?.verificationMetadata?.proofs?.length > 0;
+};
+
+/**
+ * Build a BotProgressIndicatorMetadata object.
+ */
+export const buildProgressIndicator = (description, steps = [], estimatedMs) => {
+    const stepsMetadata = steps.map(step => {
+        const s = {
+            statusTitle: step.title,
+            status: step.status ?? PlanningStepStatus.IN_PROGRESS
+        };
+        if (step.body) s.statusBody = step.body;
+        if (step.isReasoning) s.isReasoning = true;
+        if (step.isEnhancedSearch) s.isEnhancedSearch = true;
+        return s;
+    });
+
+    const indicator = { stepsMetadata };
+    if (description) indicator.progressDescription = description;
+    if (estimatedMs != null) indicator.estimatedCompletionTime = estimatedMs;
+    return indicator;
+};
+
+/**
+ * Build the native Meta AI compositing placeholder (for compatible clients only).
+ */
+export const buildCompositingPlaceholder = ({
+    description = 'Thinking…',
+    steps = [],
+    estimatedMs,
+    placeholderText = '',
+    verificationMetadata
+} = {}) => {
+    const progressIndicatorMetadata = buildProgressIndicator(description, steps, estimatedMs);
+
+    const textEncoder = new TextEncoder();
+    const unifiedData = textEncoder.encode(JSON.stringify({
+        response_id: crypto.randomUUID(),
+        sections: placeholderText ? [{
+            view_model: {
+                primitive: {
+                    text: placeholderText,
+                    inline_entities: [],
+                    __typename: 'GenAIMarkdownTextUXPrimitive'
+                },
+                __typename: 'GenAISingleLayoutViewModel'
+            }
+        }] : []
+    }));
+
+    const richResponseMessage = {
+        messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD,
+        unifiedResponse: { data: unifiedData },
+        submessages: []
+    };
+
+    return {
+        messageContextInfo: {
+            botMetadata: {
+                pluginMetadata: {},
+                progressIndicatorMetadata,
+                botRenderingConfigMetadata: BOT_RENDERING_CONFIG_METADATA,
+                ...(verificationMetadata ? { verificationMetadata } : {})
+            }
+        },
+        botForwardedMessage: {
+            message: { richResponseMessage }
+        }
+    };
+};
+
+/**
+ * Build a plain-text placeholder that works on ALL WhatsApp clients.
+ */
+export const buildPlainPlaceholder = (description = 'Thinking…', steps = [], placeholderText = '') => {
+    const stepLines = steps.map(step => {
+        const icon = step.status === PlanningStepStatus.DONE ? '✓' :
+                     step.status === PlanningStepStatus.FAILED ? '✗' : '○';
+        return `${icon} ${step.title}`;
+    }).join('\n');
+
+    let text = `_${description}_`;
+    if (stepLines) text += `\n\n${stepLines}`;
+    if (placeholderText) text += `\n\n${placeholderText}`;
+
+    return { text };
+};
+
+/**
+ * metaTyping — sends the progress/compositing indicator.
+ * UNIVERSAL: plain text is the default. Native Meta progress is sent only when
+ * useNativeMeta is true, forceMetaRendering is enabled, and trusted verification
+ * metadata is supplied in socket.config.metaAiRendering.
+ */
+export const metaTyping = async (sock, jid, {
+    description = 'Thinking…',
+    steps = [],
+    estimatedMs,
+    placeholderText = '',
+    useNativeMeta = false
+} = {}) => {
+    // Premium feature — on unlicensed copies the progress indicator is skipped
+    // entirely (callers already guard deletes with placeholder?.key).
+    if (!premiumEnabled(sock.config?.logger)) {
+        return { key: undefined };
+    }
+    // Show typing indicator
+    await sock.sendPresenceUpdate('composing', jid);
+
+    if (useNativeMeta && supportsMetaRendering(jid, sock.config)) {
+        const placeholder = buildCompositingPlaceholder({
+            description,
+            steps,
+            estimatedMs,
+            placeholderText,
+            verificationMetadata: sock.config?.metaAiRendering?.verificationMetadata
+        });
+        return sock.sendMessage(jid, { raw: true, ...placeholder });
+    }
+
+    // Universal fallback: plain text placeholder
+    const plainSteps = steps.map(s => ({ ...s, status: PlanningStepStatus.IN_PROGRESS }));
+    const placeholder = buildPlainPlaceholder(description, plainSteps, placeholderText);
+    return sock.sendMessage(jid, placeholder);
+};
+
+/**
+ * sendMetaComposited — full Meta AI flow (UNIVERSAL).
+ *   1. Send progress indicator
+ *   2. Wait thinkingMs
+ *   3. Delete placeholder
+ *   4. Send final message fresh
+ */
+export const sendMetaComposited = async (sock, jid, content, {
+    thinkingMs = 2000,
+    description = 'Thinking…',
+    steps = [],
+    placeholderText = '',
+    sendOptions = {},
+    useNativeMeta = false
+} = {}) => {
+    // Premium feature — on unlicensed copies skip the whole Meta AI flow and
+    // just send the final content (the composer downgrades it to plain text).
+    if (!premiumEnabled(sock.config?.logger)) {
+        return sock.sendMessage(jid, content, sendOptions);
+    }
+    const placeholder = await metaTyping(sock, jid, {
+        description, steps, estimatedMs: thinkingMs, placeholderText, useNativeMeta
+    });
+
+    try {
+        await delay(thinkingMs);
+        if (placeholder?.key) {
+            await sock.sendMessage(jid, { delete: placeholder.key });
+        }
+    } catch (_) {}
+
+    await sock.sendPresenceUpdate('paused', jid);
+    return sock.sendMessage(jid, content, sendOptions);
+};
+
+/**
+ * Convenience: build a steps array from plain strings.
+ */
+export const buildSteps = (titles, status = PlanningStepStatus.IN_PROGRESS) =>
+    titles.map(title => ({ title, status }));

package/lib/Utils/native-flow.js

@@ -0,0 +1,100 @@
+const parseJsonObject = (value) => {
+    if (!value) {
+        return {};
+    }
+    if (typeof value === 'object') {
+        return value;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+};
+
+/**
+ * Extracts a native-flow response from an incoming WhatsApp message.
+ * Supports ordinary quick replies, single-select responses, and WhatsApp Flow
+ * form responses carried by nativeFlowResponseMessage.paramsJson.
+ */
+export const parseNativeFlowResponse = (message) => {
+    const content = message?.message || message;
+    const response = content?.interactiveResponseMessage?.nativeFlowResponseMessage ||
+        content?.nativeFlowResponseMessage;
+    if (!response) {
+        return null;
+    }
+    const params = parseJsonObject(response.paramsJson);
+    const actionPayload = params.flow_action_payload || params.flowActionPayload || {};
+    const data = params.data || params.response || params.form_data || params.formData || actionPayload.data || {};
+    return {
+        name: response.name || '',
+        version: response.version,
+        paramsJson: response.paramsJson || '',
+        params,
+        isFlow: response.name === 'galaxy_message' || response.name === 'flow' ||
+            !!(params.flow_id || params.flow_token || params.flow_message_version),
+        flowId: params.flow_id || params.flowId,
+        flowToken: params.flow_token || params.flowToken,
+        screen: params.screen || actionPayload.screen,
+        action: params.flow_action || params.flowAction || actionPayload.action,
+        actionPayload,
+        data,
+        buttonId: params.id || params.button_id || params.buttonId,
+        displayText: params.display_text || params.displayText,
+        raw: response
+    };
+};
+
+/**
+ * Extracts only completed or navigated WhatsApp Flow data from a message.
+ * Returns null for ordinary native-flow buttons.
+ */
+export const parseWhatsAppFlowResponse = (message) => {
+    const response = parseNativeFlowResponse(message);
+    if (!response?.isFlow) {
+        return null;
+    }
+    return response;
+};
+
+/**
+ * Builds the native-flow button payload used to launch a published WhatsApp Flow.
+ * The caller must own the Flow ID/token and publish the Flow through Meta's
+ * WhatsApp Flows API or Flow Builder.
+ */
+export const buildWhatsAppFlowButton = ({
+    flowId,
+    flowToken,
+    cta = 'Open form',
+    action = 'navigate',
+    actionPayload,
+    mode = 'published',
+    flowMessageVersion = '3',
+    metadata,
+    name = 'galaxy_message'
+} = {}) => {
+    if (!flowId) {
+        throw new TypeError('flowId is required to launch a WhatsApp Flow');
+    }
+    if (!flowToken) {
+        throw new TypeError('flowToken is required to launch a WhatsApp Flow');
+    }
+    return {
+        name,
+        flow_message_version: String(flowMessageVersion),
+        flow_token: String(flowToken),
+        flow_id: String(flowId),
+        flow_cta: String(cta),
+        flow_action: action,
+        ...(actionPayload ? { flow_action_payload: actionPayload } : {}),
+        ...(metadata ? { flow_metadata: metadata } : {})
+    };
+};
+
+export const makeWhatsAppFlowButton = (flow) => ({
+    name: flow?.nativeFlowName || 'galaxy_message',
+    buttonParamsJson: JSON.stringify(buildWhatsAppFlowButton(flow))
+});

package/lib/Utils/noise-handler.js

@@ -0,0 +1,200 @@
+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);
+        }
+    };
+};

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

@@ -0,0 +1,39 @@
+/**
+ * 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 };
+}