zapo-js 0.3.0 → 1.0.0

package/dist/message/context-info.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContextInfoProto = buildContextInfoProto;
+exports.applyContextInfo = applyContextInfo;
+exports.pickIncomingExpirationSeconds = pickIncomingExpirationSeconds;
+exports.resolveSendContextInfo = resolveSendContextInfo;
+const jid_1 = require("../protocol/jid");
+function buildContextInfoProto(input) {
+    const ctx = {};
+    if (input.quotedMessageId !== undefined)
+        ctx.stanzaId = input.quotedMessageId;
+    if (input.quotedParticipant !== undefined)
+        ctx.participant = input.quotedParticipant;
+    if (input.quotedRemoteJid !== undefined)
+        ctx.remoteJid = input.quotedRemoteJid;
+    if (input.quotedMessage !== undefined)
+        ctx.quotedMessage = input.quotedMessage;
+    if (input.isForwarded !== undefined)
+        ctx.isForwarded = input.isForwarded;
+    if (input.forwardingScore !== undefined)
+        ctx.forwardingScore = input.forwardingScore;
+    if (input.mentionedJids && input.mentionedJids.length > 0) {
+        ctx.mentionedJid = [...input.mentionedJids];
+    }
+    if (input.isSpoiler !== undefined)
+        ctx.isSpoiler = input.isSpoiler;
+    if (input.expirationSeconds !== undefined)
+        ctx.expiration = input.expirationSeconds;
+    if (input.groupSubject !== undefined)
+        ctx.groupSubject = input.groupSubject;
+    if (input.parentGroupJid !== undefined)
+        ctx.parentGroupJid = input.parentGroupJid;
+    if (input.raw) {
+        Object.assign(ctx, input.raw);
+    }
+    return ctx;
+}
+function applyContextInfo(message, ctx) {
+    if (!ctx)
+        return message;
+    const proto = buildContextInfoProto(ctx);
+    if (!hasAnyKey(proto))
+        return message;
+    const next = { ...message };
+    if (typeof next.conversation === 'string' && !next.extendedTextMessage) {
+        next.extendedTextMessage = { text: next.conversation };
+        delete next.conversation;
+    }
+    if (!hasAnyKey(next)) {
+        next.extendedTextMessage = {};
+    }
+    const target = pickContextInfoTarget(next);
+    if (!target) {
+        throw new Error('cannot apply contextInfo: no compatible submessage found');
+    }
+    target.contextInfo = { ...target.contextInfo, ...proto };
+    return next;
+}
+/**
+ * Reads the disappearing-message TTL (`contextInfo.expiration`) from the first
+ * submessage that carries it. Unwraps `ephemeralMessage` if present. Returns
+ * `undefined` when no submessage has an `expiration` set.
+ */
+function pickIncomingExpirationSeconds(message) {
+    if (!message)
+        return undefined;
+    const inner = message.ephemeralMessage?.message ?? message;
+    for (const key of Object.keys(inner)) {
+        const value = inner[key];
+        if (value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            !(value instanceof Uint8Array)) {
+            const ctx = value.contextInfo;
+            if (ctx?.expiration !== undefined && ctx.expiration !== null) {
+                return ctx.expiration;
+            }
+        }
+    }
+    return undefined;
+}
+function pickContextInfoTarget(message) {
+    for (const key of Object.keys(message)) {
+        const value = message[key];
+        if (value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            !(value instanceof Uint8Array)) {
+            return value;
+        }
+    }
+    return null;
+}
+function resolveSendContextInfo(input) {
+    const ctx = {
+        ...(input.contentLevel ?? {}),
+        ...(input.optionsLevel ?? {})
+    };
+    if (input.quote) {
+        const q = input.quote;
+        ctx.quotedMessageId = q.id ?? q.key?.id ?? ctx.quotedMessageId;
+        const explicit = q.participant ?? q.key?.participant;
+        const quotedRemote = q.remoteJid ?? q.key?.remoteJid;
+        const dmFallback = explicit === undefined && quotedRemote && !(0, jid_1.isGroupOrBroadcastJid)(quotedRemote)
+            ? q.key?.fromMe
+                ? input.meLid
+                : quotedRemote
+            : undefined;
+        ctx.quotedParticipant = explicit ?? dmFallback ?? ctx.quotedParticipant;
+        ctx.quotedRemoteJid = quotedRemote ?? ctx.quotedRemoteJid;
+        ctx.quotedMessage = q.message ?? ctx.quotedMessage;
+    }
+    if (input.forward) {
+        const explicit = typeof input.forward === 'object' ? input.forward.score : undefined;
+        const base = ctx.forwardingScore ?? 0;
+        ctx.isForwarded = true;
+        ctx.forwardingScore = explicit ?? (base > 0 ? base + 1 : 1);
+    }
+    if (input.mentions?.length) {
+        ctx.mentionedJids = input.mentions;
+    }
+    return hasAnyKey(ctx) ? ctx : null;
+}
+function hasAnyKey(value) {
+    for (const _ in value) {
+        return true;
+    }
+    return false;
+}

package/dist/message/{addon-crypto.js → crypto/addon-crypto.js}

@@ -8,16 +8,18 @@ exports.identifyEncryptedAddon = identifyEncryptedAddon;
 exports.decodeAddonPlaintext = decodeAddonPlaintext;
 exports.resolveParentMessageSecret = resolveParentMessageSecret;
 exports.resolvePollOptionNames = resolvePollOptionNames;
-const _crypto_1 = require("../crypto/index.js");
-const content_1 = require("./content");
-const use_case_secret_1 = require("./use-case-secret");
-const _proto_1 = require("../proto.js");
-const bytes_1 = require("../util/bytes");
+const _crypto_1 = require("../../crypto/index.js");
+const use_case_secret_1 = require("../crypto/use-case-secret");
+const content_1 = require("../encode/content");
+const _proto_1 = require("../../proto.js");
+const bytes_1 = require("../../util/bytes");
 const WA_ADDON_ENCRYPTION_NONCE_BYTES = 12;
+/** Returns `true` when an addon kind binds its AES-GCM ciphertext to additional data (polls + event responses). */
 function shouldUseAddonAdditionalData(modificationType) {
     return (modificationType === use_case_secret_1.WA_USE_CASE_SECRET_MODIFICATION_TYPES.POLL_VOTE ||
         modificationType === use_case_secret_1.WA_USE_CASE_SECRET_MODIFICATION_TYPES.EVENT_RESPONSE);
 }
+/** Builds the canonical AES-GCM `additionalData` bytes for an addon (stanza id + NUL + sender). */
 function buildAddonAdditionalData(stanzaId, addOnSenderJid) {
     if (!stanzaId.trim()) {
         throw new Error('stanza id must be a non-empty string');
@@ -27,6 +29,7 @@ function buildAddonAdditionalData(stanzaId, addOnSenderJid) {
     }
     return bytes_1.TEXT_ENCODER.encode(`${stanzaId}\u0000${addOnSenderJid}`);
 }
+/** Encrypts an addon payload (poll vote, reaction, edit, ...) with the per-use-case secret. */
 async function encryptAddonPayload(input) {
     const secret = await (0, use_case_secret_1.createUseCaseSecret)({
         messageSecret: (0, use_case_secret_1.assertMessageSecret)(input.messageSecret),
@@ -35,11 +38,11 @@ async function encryptAddonPayload(input) {
         modificationSender: input.modificationSender,
         modificationType: input.modificationType
     });
-    const key = await (0, _crypto_1.importAesGcmKey)(secret, ['encrypt']);
     const iv = assertAddonIv(input.iv);
     const additionalData = resolveAddonAdditionalData(input);
-    return (0, _crypto_1.aesGcmEncrypt)(key, iv, (0, bytes_1.toBytesView)(input.payload), additionalData);
+    return (0, _crypto_1.aesGcmEncrypt)(secret, iv, (0, bytes_1.toBytesView)(input.payload), additionalData);
 }
+/** Decrypts an addon payload encrypted with {@link encryptAddonPayload}. */
 async function decryptAddonPayload(input) {
     const secret = await (0, use_case_secret_1.createUseCaseSecret)({
         messageSecret: (0, use_case_secret_1.assertMessageSecret)(input.messageSecret),
@@ -48,11 +51,15 @@ async function decryptAddonPayload(input) {
         modificationSender: input.modificationSender,
         modificationType: input.modificationType
     });
-    const key = await (0, _crypto_1.importAesGcmKey)(secret, ['decrypt']);
     const iv = assertAddonIv(input.iv);
     const additionalData = resolveAddonAdditionalData(input);
-    return (0, _crypto_1.aesGcmDecrypt)(key, iv, (0, bytes_1.toBytesView)(input.ciphertext), additionalData);
+    return (0, _crypto_1.aesGcmDecrypt)(secret, iv, (0, bytes_1.toBytesView)(input.ciphertext), additionalData);
 }
+/**
+ * Inspects a message and, when it contains an encrypted addon (reaction,
+ * poll vote, edit, comment, event response, ...), returns the parsed
+ * envelope with its kind and target message key. Returns `null` otherwise.
+ */
 function identifyEncryptedAddon(message) {
     const msg = (0, content_1.unwrapMessage)(message);
     if (msg.encReactionMessage) {
@@ -107,8 +114,54 @@ function identifyEncryptedAddon(message) {
             };
         }
     }
+    if (msg.secretEncryptedMessage) {
+        const { targetMessageKey, encPayload, encIv, secretEncType } = msg.secretEncryptedMessage;
+        if (targetMessageKey?.id &&
+            encPayload &&
+            encIv &&
+            encIv.byteLength === WA_ADDON_ENCRYPTION_NONCE_BYTES) {
+            const mapped = mapSecretEncType(secretEncType);
+            if (mapped) {
+                return {
+                    kind: mapped.kind,
+                    targetMessageKey,
+                    encPayload,
+                    encIv,
+                    modificationType: mapped.modificationType,
+                    raw: message
+                };
+            }
+        }
+    }
     return null;
 }
+function mapSecretEncType(secretEncType) {
+    switch (secretEncType) {
+        case _proto_1.proto.Message.SecretEncryptedMessage.SecretEncType.MESSAGE_EDIT:
+            return {
+                kind: 'message_edit',
+                modificationType: use_case_secret_1.WA_USE_CASE_SECRET_MODIFICATION_TYPES.MESSAGE_EDIT
+            };
+        case _proto_1.proto.Message.SecretEncryptedMessage.SecretEncType.EVENT_EDIT:
+            return {
+                kind: 'event_edit',
+                modificationType: use_case_secret_1.WA_USE_CASE_SECRET_MODIFICATION_TYPES.EVENT_EDIT_ENCRYPTED
+            };
+        case _proto_1.proto.Message.SecretEncryptedMessage.SecretEncType.POLL_EDIT:
+            return {
+                kind: 'poll_edit',
+                modificationType: use_case_secret_1.WA_USE_CASE_SECRET_MODIFICATION_TYPES.POLL_EDIT_ENCRYPTED
+            };
+        case _proto_1.proto.Message.SecretEncryptedMessage.SecretEncType.POLL_ADD_OPTION:
+            return {
+                kind: 'poll_add_option',
+                modificationType: use_case_secret_1.WA_USE_CASE_SECRET_MODIFICATION_TYPES.POLL_ADD_OPTION
+            };
+        default:
+            return null;
+    }
+}
+/** Decodes the decrypted addon plaintext into its typed protobuf message based on `kind`. */
 function decodeAddonPlaintext(kind, plaintext) {
     switch (kind) {
         case 'reaction':
@@ -123,6 +176,11 @@ function decodeAddonPlaintext(kind, plaintext) {
             return { kind, eventResponse: _proto_1.proto.Message.EventResponseMessage.decode(plaintext) };
         case 'comment':
             return { kind, comment: _proto_1.proto.Message.CommentMessage.decode(plaintext) };
+        case 'message_edit':
+        case 'event_edit':
+        case 'poll_edit':
+        case 'poll_add_option':
+            return { kind, message: _proto_1.proto.Message.decode(plaintext) };
     }
 }
 async function resolveParentMessageSecret(targetMessageId, messageSecretStore, messageStore) {
@@ -165,7 +223,7 @@ async function resolvePollOptionNames(selectedOptions, pollCreationMessageId, me
     for (const option of options) {
         if (!option.optionName)
             continue;
-        const hash = await (0, _crypto_1.sha256)(bytes_1.TEXT_ENCODER.encode(option.optionName));
+        const hash = (0, _crypto_1.sha256)(bytes_1.TEXT_ENCODER.encode(option.optionName));
         hashToName.set((0, bytes_1.bytesToHex)(hash), option.optionName);
     }
     const names = [];

package/dist/message/{icdc.js → crypto/icdc.js}

@@ -3,13 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeDeviceKeyHash = computeDeviceKeyHash;
 exports.resolveIcdcMeta = resolveIcdcMeta;
 exports.injectDeviceListMetadata = injectDeviceListMetadata;
-const _crypto_1 = require("../crypto/index.js");
-const jid_1 = require("../protocol/jid");
-const bytes_1 = require("../util/bytes");
+const _crypto_1 = require("../../crypto/index.js");
+const jid_1 = require("../../protocol/jid");
 const ICDC_DEFAULT_HASH_LENGTH = 8;
 const ICDC_FRESHNESS_THRESHOLD_MS = 30 * 24 * 60 * 60 * 1000;
 const DEVICE_LIST_METADATA_VERSION = 2;
-async function computeDeviceKeyHash(identityKeys, hashLength) {
+function computeDeviceKeyHash(identityKeys, hashLength) {
     const length = hashLength ?? ICDC_DEFAULT_HASH_LENGTH;
     if (identityKeys.length === 0) {
         return new Uint8Array(length);
@@ -19,8 +18,7 @@ async function computeDeviceKeyHash(identityKeys, hashLength) {
         rawKeys[i] =
             identityKeys[i].byteLength === 33 ? (0, _crypto_1.toRawPubKey)(identityKeys[i]) : identityKeys[i];
     }
-    const combined = (0, bytes_1.concatBytes)(rawKeys);
-    const hash = await (0, _crypto_1.sha256)(combined);
+    const hash = (0, _crypto_1.sha256)(rawKeys);
     return hash.subarray(0, length);
 }
 async function resolveIcdcMeta(deviceJids, identityStore, updatedAtMs, localIdentity, hashLength) {
@@ -47,7 +45,7 @@ async function resolveIcdcMeta(deviceJids, identityStore, updatedAtMs, localIden
     if (keys.length === 0) {
         return null;
     }
-    const keyHash = await computeDeviceKeyHash(keys, hashLength);
+    const keyHash = computeDeviceKeyHash(keys, hashLength);
     const timestamp = updatedAtMs !== undefined && Date.now() - updatedAtMs < ICDC_FRESHNESS_THRESHOLD_MS
         ? Math.floor(updatedAtMs / 1000)
         : undefined;

package/dist/message/crypto/phash.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePhashV2 = computePhashV2;
+const core_1 = require("../../crypto/core");
+const constants_1 = require("../../protocol/constants");
+const bytes_1 = require("../../util/bytes");
+const PHASH_DIGEST_PREFIX = 6;
+const CHAR_DOT = 0x2e;
+const CHAR_ZERO = 0x30;
+const CHAR_COLON = 0x3a;
+const CHAR_AT = 0x40;
+const CHAR_C = 0x63;
+const CHAR_U = 0x75;
+const CHAR_S = 0x73;
+const MAX_PARTICIPANTS = 2048;
+const PER_WID_BYTES = 96;
+const SCRATCH = new Uint8Array(MAX_PARTICIPANTS * PER_WID_BYTES);
+const OFFSETS = new Uint32Array(MAX_PARTICIPANTS + 1);
+const ORDER = new Uint32Array(MAX_PARTICIPANTS);
+function computePhashV2(participants) {
+    if (participants.length === 0)
+        return '2:';
+    const n = participants.length;
+    if (n > MAX_PARTICIPANTS) {
+        throw new Error(`phash participant count ${n} exceeds MAX_PARTICIPANTS ${MAX_PARTICIPANTS}`);
+    }
+    let off = 0;
+    for (let i = 0; i < n; i += 1) {
+        OFFSETS[i] = off;
+        const nextOff = writeCanonicalUtf8(SCRATCH, off, participants[i]);
+        if (nextOff > SCRATCH.length) {
+            throw new Error(`phash canonical buffer overflow at participant ${i}: needs ${nextOff} bytes, scratch is ${SCRATCH.length}`);
+        }
+        off = nextOff;
+    }
+    OFFSETS[n] = off;
+    for (let i = 0; i < n; i += 1)
+        ORDER[i] = i;
+    ORDER.subarray(0, n).sort((a, b) => compareScratchSlice(SCRATCH, OFFSETS, a, b));
+    const parts = new Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const idx = ORDER[i];
+        parts[i] = SCRATCH.subarray(OFFSETS[idx], OFFSETS[idx + 1]);
+    }
+    const digest = (0, core_1.sha256)(parts);
+    return `2:${(0, bytes_1.bytesToBase64)(digest.subarray(0, PHASH_DIGEST_PREFIX))}`;
+}
+function writeCanonicalUtf8(out, start, jid) {
+    const atIndex = jid.indexOf('@');
+    if (atIndex < 1 || atIndex >= jid.length - 1) {
+        return writeAscii(out, start, jid, 0, jid.length);
+    }
+    const colonIndex = jid.indexOf(':', 0);
+    const userEnd = colonIndex >= 0 && colonIndex < atIndex ? colonIndex : atIndex;
+    const hasZeroAgent = userEnd >= 2 &&
+        jid.charCodeAt(userEnd - 2) === CHAR_DOT &&
+        jid.charCodeAt(userEnd - 1) === CHAR_ZERO;
+    const baseUserEnd = hasZeroAgent ? userEnd - 2 : userEnd;
+    let off = writeAscii(out, start, jid, 0, baseUserEnd);
+    out[off++] = CHAR_DOT;
+    out[off++] = CHAR_ZERO;
+    out[off++] = CHAR_COLON;
+    let device = 0;
+    if (colonIndex >= 0 && colonIndex < atIndex) {
+        for (let i = colonIndex + 1; i < atIndex; i += 1) {
+            const digit = jid.charCodeAt(i) - CHAR_ZERO;
+            if (digit < 0 || digit > 9) {
+                device = 0;
+                break;
+            }
+            device = device * 10 + digit;
+            if (device > Number.MAX_SAFE_INTEGER) {
+                device = 0;
+                break;
+            }
+        }
+    }
+    off = writeUintAscii(out, off, device);
+    out[off++] = CHAR_AT;
+    const serverStart = atIndex + 1;
+    const serverLen = jid.length - serverStart;
+    const isCUs = serverLen === 4 &&
+        jid.charCodeAt(serverStart) === CHAR_C &&
+        jid.charCodeAt(serverStart + 1) === CHAR_DOT &&
+        jid.charCodeAt(serverStart + 2) === CHAR_U &&
+        jid.charCodeAt(serverStart + 3) === CHAR_S;
+    if (isCUs) {
+        off = writeAscii(out, off, constants_1.WA_DEFAULTS.HOST_DOMAIN, 0, constants_1.WA_DEFAULTS.HOST_DOMAIN.length);
+    }
+    else {
+        off = writeAscii(out, off, jid, serverStart, jid.length);
+    }
+    return off;
+}
+function writeAscii(out, outOff, str, start, end) {
+    for (let i = start; i < end; i += 1) {
+        out[outOff + (i - start)] = str.charCodeAt(i);
+    }
+    return outOff + (end - start);
+}
+function writeUintAscii(out, off, value) {
+    if (value === 0) {
+        out[off] = CHAR_ZERO;
+        return off + 1;
+    }
+    let temp = value;
+    let digits = 0;
+    while (temp > 0) {
+        digits += 1;
+        temp = (temp - (temp % 10)) / 10;
+    }
+    let cursor = off + digits - 1;
+    let v = value;
+    while (v > 0) {
+        out[cursor] = CHAR_ZERO + (v % 10);
+        cursor -= 1;
+        v = (v - (v % 10)) / 10;
+    }
+    return off + digits;
+}
+function compareScratchSlice(scratch, offsets, a, b) {
+    const aStart = offsets[a];
+    const aEnd = offsets[a + 1];
+    const bStart = offsets[b];
+    const bEnd = offsets[b + 1];
+    const aLen = aEnd - aStart;
+    const bLen = bEnd - bStart;
+    const cmpLen = aLen < bLen ? aLen : bLen;
+    for (let k = 0; k < cmpLen; k += 1) {
+        const av = scratch[aStart + k];
+        const bv = scratch[bStart + k];
+        if (av !== bv)
+            return av - bv;
+    }
+    return aLen - bLen;
+}

package/dist/message/{reporting-token.js → crypto/reporting-token.js}

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WA_REPORTING_TOKEN_VERSION = void 0;
 exports.buildReportingTokenArtifacts = buildReportingTokenArtifacts;
-const _crypto_1 = require("../crypto/index.js");
-const _proto_1 = require("../proto.js");
-const bytes_1 = require("../util/bytes");
+const _crypto_1 = require("../../crypto/index.js");
+const _proto_1 = require("../../proto.js");
+const bytes_1 = require("../../util/bytes");
 const WA_REPORTING_TOKEN_BYTES = 16;
 const WA_REPORTING_TOKEN_KEY_BYTES = 32;
 const WA_REPORTING_TOKEN_USE_CASE = 'Report Token';
@@ -13,6 +13,7 @@ const WA_REPORTING_TOKEN_CONFIG_BYTES = (0, bytes_1.base64ToBytesChecked)(WA_REP
 exports.WA_REPORTING_TOKEN_VERSION = 2;
 let reportingTokenConfigSpec = null;
 const reportingTokenConfigCache = new Map();
+// eslint-disable-next-line @typescript-eslint/require-await
 async function buildReportingTokenArtifacts(input) {
     const stanzaId = input.stanzaId.trim();
     if (!stanzaId || !isMessageReportingTokenCompatible(input.message)) {
@@ -27,9 +28,8 @@ async function buildReportingTokenArtifacts(input) {
         return null;
     }
     const secretInfo = bytes_1.TEXT_ENCODER.encode(stanzaId + input.senderUserJid + input.remoteJid + WA_REPORTING_TOKEN_USE_CASE);
-    const reportingTokenKey = await (0, _crypto_1.hkdf)(messageSecret, null, secretInfo, WA_REPORTING_TOKEN_KEY_BYTES);
-    const hmacKey = await (0, _crypto_1.importHmacKey)(reportingTokenKey);
-    const reportingToken = (await (0, _crypto_1.hmacSign)(hmacKey, reportingTokenContent)).subarray(0, WA_REPORTING_TOKEN_BYTES);
+    const reportingTokenKey = (0, _crypto_1.hkdf)(messageSecret, null, secretInfo, WA_REPORTING_TOKEN_KEY_BYTES);
+    const reportingToken = (0, _crypto_1.hmacSha256Sign)(reportingTokenKey, reportingTokenContent).subarray(0, WA_REPORTING_TOKEN_BYTES);
     const version = input.version ?? exports.WA_REPORTING_TOKEN_VERSION;
     return {
         node: {

package/dist/message/{use-case-secret.js → crypto/use-case-secret.js}

@@ -4,8 +4,8 @@ exports.WA_USE_CASE_SECRET_MODIFICATION_TYPES = exports.WA_MESSAGE_SECRET_BYTES
 exports.assertMessageSecret = assertMessageSecret;
 exports.ensureMessageSecret = ensureMessageSecret;
 exports.createUseCaseSecret = createUseCaseSecret;
-const _crypto_1 = require("../crypto/index.js");
-const bytes_1 = require("../util/bytes");
+const _crypto_1 = require("../../crypto/index.js");
+const bytes_1 = require("../../util/bytes");
 exports.WA_MESSAGE_SECRET_BYTES = 32;
 exports.WA_USE_CASE_SECRET_MODIFICATION_TYPES = Object.freeze({
     POLL_VOTE: 'Poll Vote',
@@ -14,8 +14,14 @@ exports.WA_USE_CASE_SECRET_MODIFICATION_TYPES = Object.freeze({
     REPORT_TOKEN: 'Report Token',
     EVENT_RESPONSE: 'Event Response',
     EVENT_EDIT_ENCRYPTED: 'Event Edit',
-    MESSAGE_EDIT: 'Message Edit'
+    MESSAGE_EDIT: 'Message Edit',
+    POLL_EDIT_ENCRYPTED: 'Poll Edit',
+    POLL_ADD_OPTION: 'Poll Add Option'
 });
+/**
+ * Validates that `messageSecret` is exactly 32 bytes and returns it as a
+ * zero-copy Uint8Array view (throws otherwise).
+ */
 function assertMessageSecret(messageSecret, context = 'message secret') {
     const bytes = (0, bytes_1.toBytesView)(messageSecret);
     if (bytes.byteLength !== exports.WA_MESSAGE_SECRET_BYTES) {
@@ -23,6 +29,11 @@ function assertMessageSecret(messageSecret, context = 'message secret') {
     }
     return bytes;
 }
+/**
+ * Returns `message` unchanged when a message secret is already present;
+ * otherwise generates a fresh 32-byte secret and attaches it under
+ * `messageContextInfo.messageSecret`.
+ */
 async function ensureMessageSecret(message) {
     const messageSecret = message.messageContextInfo?.messageSecret;
     if (messageSecret && messageSecret.byteLength > 0) {
@@ -37,6 +48,12 @@ async function ensureMessageSecret(message) {
         }
     };
 }
+/**
+ * Derives the per-use-case secret (poll vote, reaction, edit, ...) via HKDF
+ * over `messageSecret` and the canonical `stanzaId + sender + sender +
+ * modificationType` info string.
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
 async function createUseCaseSecret(input) {
     if (!input.stanzaId.trim()) {
         throw new Error('stanza id must be a non-empty string');