@softtynet/zca-js 2.2.8 → 2.2.10

package/dist/core/zcloud-client.js

@@ -0,0 +1,83 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { decryptZCloudAES, encryptZCloudAES } from "../crypto/index.js";
+/**
+ * Thực thi request tới hệ sinh thái ZCloud (`zcld.chat.zalo.me`) kèm cơ chế:
+ * 1. Tự động lấy `viewer_key` & `enk` từ bộ nhớ đệm (`ctx.zcloudViewerKeyCache`) nếu người dùng không truyền.
+ * 2. Tự động thử lại (Auto-Retry 1 lần với `forceRefresh = true`) nếu khóa `viewer_key` trong cache bị máy chủ từ chối do hết hạn sớm.
+ * 3. Tự động giải mã payload AES-256-CBC (Random 16-byte IV - module `98yS`).
+ */
+export async function requestZCloudDecrypted(api, utils, options) {
+    const executeOnce = async (keyInfo) => {
+        if (!keyInfo?.viewer_key || !keyInfo?.enk) {
+            throw new ZaloApiError("Invalid CloudViewerKey");
+        }
+        const targetUrl = options.paramsPayload
+            ? utils.makeURL(options.url, {
+                params: encryptZCloudAES(JSON.stringify(options.paramsPayload), keyInfo.enk),
+            })
+            : options.url;
+        const response = await utils.request(targetUrl, {
+            method: options.method ?? "GET",
+            headers: {
+                "cloud-viewer-key": keyInfo.viewer_key,
+            },
+            ...(options.body ? { body: options.body } : {}),
+        });
+        const json = (await response.json());
+        return { json, keyInfo };
+    };
+    const initialKey = options.viewerKeyInfo ?? (await api.getCloudViewerKey(false));
+    let { json, keyInfo } = await executeOnce(initialKey);
+    if (!options.viewerKeyInfo && json.error_code !== 0 && json.error_code !== -904) {
+        const refreshedKey = await api.getCloudViewerKey(true);
+        ({ json, keyInfo } = await executeOnce(refreshedKey));
+    }
+    if (json.error_code !== 0 && json.error_code !== -904) {
+        throw new ZaloApiError(json.error_message || "ZCloud request failed", json.error_code);
+    }
+    if (!json.data) {
+        if (options.allowEmptyDataOn904) {
+            return {};
+        }
+        throw new ZaloApiError("Empty ZCloud response data", json.error_code);
+    }
+    const decrypted = decryptZCloudAES(json.data, keyInfo.enk);
+    return JSON.parse(decrypted);
+}
+/**
+ * Thực thi request tới hệ sinh thái ZFamily (`zfml.chat.zalo.me`) kèm cơ chế tự động quản lý khóa,
+ * tự động làm mới khi khóa hết hạn và giải mã AES-256-CBC (Random 16-byte IV - module `98yS`).
+ */
+export async function requestZFamilyDecrypted(api, utils, options) {
+    const executeOnce = async (keyInfo) => {
+        if (!keyInfo?.viewer_key || !keyInfo?.enk) {
+            throw new ZaloApiError("Invalid FamilyViewerKey");
+        }
+        const response = await utils.request(options.url, {
+            method: options.method ?? "GET",
+            headers: {
+                "zfamily-viewer-key": keyInfo.viewer_key,
+            },
+            ...(options.body ? { body: options.body } : {}),
+        });
+        const json = (await response.json());
+        return { json, keyInfo };
+    };
+    const initialKey = options.viewerKeyInfo ?? (await api.getFamilyViewerKey(false));
+    let { json, keyInfo } = await executeOnce(initialKey);
+    if (!options.viewerKeyInfo && json.error_code !== 0 && json.error_code !== -904) {
+        const refreshedKey = await api.getFamilyViewerKey(true);
+        ({ json, keyInfo } = await executeOnce(refreshedKey));
+    }
+    if (json.error_code !== 0 && json.error_code !== -904) {
+        throw new ZaloApiError(json.error_message || "ZFamily request failed", json.error_code);
+    }
+    if (!json.data) {
+        if (options.allowEmptyDataOn904) {
+            return {};
+        }
+        throw new ZaloApiError("Empty ZFamily response data", json.error_code);
+    }
+    const decrypted = decryptZCloudAES(json.data, keyInfo.enk);
+    return JSON.parse(decrypted);
+}

package/dist/crypto/aes.d.ts

@@ -0,0 +1,34 @@
+import cryptojs from "crypto-js";
+export declare class ParamsEncryptor {
+    private zcid;
+    private enc_ver;
+    private zcid_ext;
+    private encryptKey;
+    constructor({ type, imei, firstLaunchTime }: {
+        type: number;
+        imei: string;
+        firstLaunchTime: number;
+    });
+    getEncryptKey(): string;
+    createZcid(type: number, imei: string, firstLaunchTime: number): void;
+    createEncryptKey(e?: number): boolean;
+    getParams(): {
+        zcid: string;
+        zcid_ext: string;
+        enc_ver: string;
+    } | null;
+    static processStr(e: string): {
+        even: null;
+        odd: null;
+    } | {
+        even: string[];
+        odd: string[];
+    };
+    static randomString(e?: number, t?: number): string;
+    static encodeAES(e: string, message: string, type: "hex" | "base64", uppercase: boolean, s?: number): string | null;
+}
+export declare function decryptResp(key: string, data: string): Record<string, unknown> | null | string;
+export declare function encodeAES(secretKey: string, data: cryptojs.lib.WordArray | string, t?: number): string | null;
+export declare function decodeAES(secretKey: string, data: string, t?: number): string | null;
+export declare function encryptPin(pin: string): string;
+export declare function validatePin(encryptedPin: string, pin: string): boolean;

package/dist/crypto/aes.js

@@ -0,0 +1,171 @@
+import cryptojs from "crypto-js";
+import crypto from "node:crypto";
+import { ZALO_PROTOCOL } from "../constants/index.js";
+import { ZaloApiError } from "../Errors/index.js";
+export class ParamsEncryptor {
+    zcid = null;
+    enc_ver;
+    zcid_ext;
+    encryptKey;
+    constructor({ type, imei, firstLaunchTime }) {
+        this.enc_ver = ZALO_PROTOCOL.ENCRYPT_VERSION;
+        this.zcid = null;
+        this.encryptKey = null;
+        this.createZcid(type, imei, firstLaunchTime);
+        this.zcid_ext = ParamsEncryptor.randomString();
+        this.createEncryptKey();
+    }
+    getEncryptKey() {
+        if (!this.encryptKey)
+            throw new ZaloApiError("getEncryptKey: didn't create encryptKey yet");
+        return this.encryptKey;
+    }
+    createZcid(type, imei, firstLaunchTime) {
+        if (!type || !imei || !firstLaunchTime)
+            throw new ZaloApiError("createZcid: missing params");
+        const msg = `${type},${imei},${firstLaunchTime}`;
+        const s = ParamsEncryptor.encodeAES("3FC4F0D2AB50057BCE0D90D9187A22B1", msg, "hex", true);
+        this.zcid = s;
+    }
+    createEncryptKey(e = 0) {
+        const t = (e, t) => {
+            const { even: n } = ParamsEncryptor.processStr(e), { even: a, odd: s } = ParamsEncryptor.processStr(t);
+            if (!n || !a || !s)
+                return !1;
+            const i = n.slice(0, 8).join("") + a.slice(0, 12).join("") + s.reverse().slice(0, 12).join("");
+            return (this.encryptKey = i), !0;
+        };
+        if (!this.zcid || !this.zcid_ext)
+            throw new ZaloApiError("createEncryptKey: zcid or zcid_ext is null");
+        try {
+            const n = cryptojs.MD5(this.zcid_ext).toString().toUpperCase();
+            if (t(n, this.zcid) || !(e < 3))
+                return !1;
+            this.createEncryptKey(e + 1);
+        }
+        catch {
+            if (e < 3)
+                this.createEncryptKey(e + 1);
+        }
+        return !0;
+    }
+    getParams() {
+        return this.zcid
+            ? {
+                zcid: this.zcid,
+                zcid_ext: this.zcid_ext,
+                enc_ver: this.enc_ver,
+            }
+            : null;
+    }
+    static processStr(e) {
+        if (!e || "string" != typeof e)
+            return {
+                even: null,
+                odd: null,
+            };
+        const [t, n] = [...e].reduce((e, t, n) => (e[n % 2].push(t), e), [[], []]);
+        return {
+            even: t,
+            odd: n,
+        };
+    }
+    static randomString(e, t) {
+        const n = e || 6, a = t && e && t > e ? t : 12;
+        let s = Math.floor(Math.random() * (a - n + 1)) + n;
+        if (s > 12) {
+            let e = "";
+            for (; s > 0;) {
+                e += Math.random()
+                    .toString(16)
+                    .substr(2, s > 12 ? 12 : s);
+                s -= 12;
+            }
+            return e;
+        }
+        return Math.random().toString(16).substr(2, s);
+    }
+    static encodeAES(e, message, type, uppercase, s = 0) {
+        if (!message)
+            return null;
+        try {
+            const encoder = "hex" == type ? cryptojs.enc.Hex : cryptojs.enc.Base64;
+            const key = cryptojs.enc.Utf8.parse(e);
+            const cfg = {
+                words: [0, 0, 0, 0],
+                sigBytes: 16,
+            };
+            const encrypted = cryptojs.AES.encrypt(message, key, {
+                iv: cfg,
+                mode: cryptojs.mode.CBC,
+                padding: cryptojs.pad.Pkcs7,
+            }).ciphertext.toString(encoder);
+            return uppercase ? encrypted.toUpperCase() : encrypted;
+        }
+        catch {
+            return s < 3 ? ParamsEncryptor.encodeAES(e, message, type, uppercase, s + 1) : null;
+        }
+    }
+}
+function decodeRespAES(key, data) {
+    data = decodeURIComponent(data);
+    const parsedKey = cryptojs.enc.Utf8.parse(key);
+    const n = {
+        words: [0, 0, 0, 0],
+        sigBytes: 16,
+    };
+    return cryptojs.AES.decrypt({
+        ciphertext: cryptojs.enc.Base64.parse(data),
+    }, parsedKey, {
+        iv: n,
+        mode: cryptojs.mode.CBC,
+        padding: cryptojs.pad.Pkcs7,
+    }).toString(cryptojs.enc.Utf8);
+}
+export function decryptResp(key, data) {
+    let n = null;
+    try {
+        n = decodeRespAES(key, data);
+        const parsed = JSON.parse(n);
+        return parsed;
+    }
+    catch {
+        return n;
+    }
+}
+export function encodeAES(secretKey, data, t = 0) {
+    try {
+        const key = cryptojs.enc.Base64.parse(secretKey);
+        return cryptojs.AES.encrypt(data, key, {
+            iv: cryptojs.enc.Hex.parse("00000000000000000000000000000000"),
+            mode: cryptojs.mode.CBC,
+            padding: cryptojs.pad.Pkcs7,
+        }).ciphertext.toString(cryptojs.enc.Base64);
+    }
+    catch {
+        return t < 3 ? encodeAES(secretKey, data, t + 1) : null;
+    }
+}
+export function decodeAES(secretKey, data, t = 0) {
+    try {
+        data = decodeURIComponent(data);
+        const key = cryptojs.enc.Base64.parse(secretKey);
+        return cryptojs.AES.decrypt({
+            ciphertext: cryptojs.enc.Base64.parse(data),
+        }, key, {
+            iv: cryptojs.enc.Hex.parse("00000000000000000000000000000000"),
+            mode: cryptojs.mode.CBC,
+            padding: cryptojs.pad.Pkcs7,
+        }).toString(cryptojs.enc.Utf8);
+    }
+    catch {
+        return t < 3 ? decodeAES(secretKey, data, t + 1) : null;
+    }
+}
+export function encryptPin(pin) {
+    return crypto.createHash("md5").update(pin).digest("hex");
+}
+export function validatePin(encryptedPin, pin) {
+    const hash = crypto.createHash("md5").update(pin).digest("hex");
+    return hash === encryptedPin;
+}

package/dist/crypto/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./aes.js";
+export * from "./zcloud-cipher.js";
+export * from "./zdb-cipher.js";
+export * from "./ws-cipher.js";

package/dist/crypto/index.js

@@ -0,0 +1,4 @@
+export * from "./aes.js";
+export * from "./zcloud-cipher.js";
+export * from "./zdb-cipher.js";
+export * from "./ws-cipher.js";

package/dist/crypto/ws-cipher.d.ts

@@ -0,0 +1,3 @@
+export declare function decodeBase64ToBuffer(data: string): Buffer;
+export declare function decodeUnit8Array(data: Uint8Array): string | null;
+export declare function decodeEventData(parsed: Record<string, unknown>, cipherKey?: string): Promise<any>;

package/dist/crypto/ws-cipher.js

@@ -0,0 +1,52 @@
+import crypto from "node:crypto";
+import pako from "pako";
+import JSONBig from "json-bigint";
+import { ZaloApiError } from "../Errors/index.js";
+export function decodeBase64ToBuffer(data) {
+    return Buffer.from(data, "base64");
+}
+export function decodeUnit8Array(data) {
+    try {
+        return new TextDecoder().decode(data);
+    }
+    catch {
+        return null;
+    }
+}
+export async function decodeEventData(parsed, cipherKey) {
+    if (typeof parsed.data !== "string")
+        throw new ZaloApiError(`Invalid data, expected string but got ${typeof parsed.data}`);
+    if (typeof parsed.encrypt !== "number")
+        throw new ZaloApiError(`Invalid encrypt type, expected number but got ${typeof parsed.encrypt}`);
+    if (parsed.encrypt < 0 || parsed.encrypt > 3)
+        throw new ZaloApiError(`Invalid encrypt type, expected 0-3 but got ${parsed.encrypt}`);
+    const rawData = parsed.data;
+    const encryptType = parsed.encrypt;
+    if (encryptType === 0)
+        return JSON.parse(rawData);
+    const decodedBuffer = decodeBase64ToBuffer(encryptType === 1 ? rawData : decodeURIComponent(rawData));
+    let decryptedBuffer = decodedBuffer;
+    if (encryptType !== 1) {
+        if (cipherKey && decodedBuffer.length >= 48) {
+            const algorithm = {
+                name: "AES-GCM",
+                iv: decodedBuffer.subarray(0, 16),
+                tagLength: 128,
+                additionalData: decodedBuffer.subarray(16, 32),
+            };
+            const dataSource = decodedBuffer.subarray(32);
+            const cryptoKey = await crypto.subtle.importKey("raw", decodeBase64ToBuffer(cipherKey), algorithm, false, [
+                "decrypt",
+            ]);
+            decryptedBuffer = await crypto.subtle.decrypt(algorithm, cryptoKey, dataSource);
+        }
+        else {
+            throw new ZaloApiError("Invalid data length or missing cipher key");
+        }
+    }
+    const decompressedBuffer = encryptType === 3 ? new Uint8Array(decryptedBuffer) : pako.inflate(decryptedBuffer);
+    const decodedData = decodeUnit8Array(decompressedBuffer);
+    if (!decodedData)
+        return;
+    return JSONBig.parse(decodedData);
+}

package/dist/crypto/zcloud-cipher.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encrypts a plaintext string for ZCloud / ZFamily APIs (`CLOUD_API` / `CLOUD_FAMILY_API`, module `"98yS"`),
+ * using AES-256-CBC with a random 16-byte IV prepended to the ciphertext before Base64 encoding.
+ */
+export declare function encryptZCloudAES(plainText: string, base64Key: string): string;
+/**
+ * Decrypts a Base64 payload from ZCloud / ZFamily APIs (`CLOUD_API` / `CLOUD_FAMILY_API`, module `"98yS"`),
+ * extracting the first 16 bytes as the AES-256-CBC IV and the remainder as PKCS#7-padded ciphertext.
+ */
+export declare function decryptZCloudAES(base64CipherText: string, base64Key: string): string;

package/dist/crypto/zcloud-cipher.js

@@ -0,0 +1,26 @@
+import crypto from "node:crypto";
+import { ZALO_PROTOCOL } from "../constants/index.js";
+/**
+ * Encrypts a plaintext string for ZCloud / ZFamily APIs (`CLOUD_API` / `CLOUD_FAMILY_API`, module `"98yS"`),
+ * using AES-256-CBC with a random 16-byte IV prepended to the ciphertext before Base64 encoding.
+ */
+export function encryptZCloudAES(plainText, base64Key) {
+    const key = Buffer.from(base64Key, "base64");
+    const iv = crypto.randomBytes(ZALO_PROTOCOL.ZCLOUD_IV_BYTE_LENGTH);
+    const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plainText, "utf8"), cipher.final()]);
+    return Buffer.concat([iv, encrypted]).toString("base64");
+}
+/**
+ * Decrypts a Base64 payload from ZCloud / ZFamily APIs (`CLOUD_API` / `CLOUD_FAMILY_API`, module `"98yS"`),
+ * extracting the first 16 bytes as the AES-256-CBC IV and the remainder as PKCS#7-padded ciphertext.
+ */
+export function decryptZCloudAES(base64CipherText, base64Key) {
+    const key = Buffer.from(base64Key, "base64");
+    const raw = Buffer.from(base64CipherText, "base64");
+    const ivLen = ZALO_PROTOCOL.ZCLOUD_IV_BYTE_LENGTH;
+    const iv = raw.subarray(0, ivLen);
+    const ciphertext = raw.subarray(ivLen);
+    const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}

package/dist/crypto/zdb-cipher.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generates an RSA 2048-bit key pair for mobile message synchronization (`pull_mobile_msg`)
+ * @returns Object containing public and private keys in both PEM and Base64 formats
+ */
+export declare function generateRSAKeyPair(): {
+    publicKeyBase64: string;
+    privateKeyBase64: string;
+    publicKey: string;
+    privateKey: string;
+};
+/**
+ * Pure-BigInt RSA CRT PKCS#1 v1.5 decryption fallback for Node.js environments
+ * where OpenSSL blocks `RSA_PKCS1_PADDING` in `crypto.privateDecrypt` (CVE-2023-46809).
+ */
+export declare function rsaDecryptPkcs1Manual(privateKeyPem: string, cipher: Buffer): Buffer;
+/**
+ * Decrypt `encrypted_key` from `syncmsg_info` using RSA private key with PKCS#1 v1.5 scheme.
+ * Automatically falls back to pure-BigInt CRT decryption if OpenSSL disables `RSA_PKCS1_PADDING`.
+ */
+export declare function decryptWithPrivateKey(privateKey: string, encryptedBase64: string): Buffer;
+/**
+ * Derives the 32-byte AES-256-CBC key for Zalo ZDB4.0 (`.db.crypt`) backup files
+ * from the raw RSA-decrypted bytes: first 32 uppercase hex characters as ASCII bytes.
+ */
+export declare function deriveZdbAesKey(decryptedRsaBytes: Buffer): Buffer;
+/**
+ * Decrypts a Zalo ZDB4.0 (`.db.crypt`) backup buffer into its plaintext ZDB4.0 container
+ * (header + table of contents + XZ stream) using 64KB independent AES-256-CBC chunks (`IV = 0`).
+ */
+export declare function decryptZdbBuffer(zdbBuffer: Buffer, aesKey: Buffer): Buffer;
+export type ZdbTocEntry = {
+    name: string;
+    size: number;
+};
+/**
+ * Parses the Table of Contents (TOC) from a decrypted ZDB4.0 container buffer,
+ * returning the list of SQLite `.db` files (`<uid>.db` / `group_<gid>.db`) and the byte offset where the XZ stream starts.
+ */
+export declare function parseZdbHeader(zdbPlaintext: Buffer): {
+    entries: ZdbTocEntry[];
+    xzOffset: number;
+};

package/dist/crypto/zdb-cipher.js

@@ -0,0 +1,167 @@
+import crypto from "node:crypto";
+import { ZALO_PROTOCOL } from "../constants/index.js";
+import { ZaloApiError } from "../Errors/index.js";
+/**
+ * Generates an RSA 2048-bit key pair for mobile message synchronization (`pull_mobile_msg`)
+ * @returns Object containing public and private keys in both PEM and Base64 formats
+ */
+export function generateRSAKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const publicKeyBase64 = publicKey
+        .toString()
+        .replace(/-----BEGIN PUBLIC KEY-----/g, "")
+        .replace(/-----END PUBLIC KEY-----/g, "")
+        .replace(/\s+/g, "");
+    const privateKeyBase64 = privateKey
+        .toString()
+        .replace(/-----BEGIN PRIVATE KEY-----/g, "")
+        .replace(/-----END PRIVATE KEY-----/g, "")
+        .replace(/\s+/g, "");
+    return { publicKeyBase64, privateKeyBase64, publicKey: publicKey.toString(), privateKey: privateKey.toString() };
+}
+function b64urlToBigInt(value) {
+    return BigInt("0x" + Buffer.from(value, "base64url").toString("hex"));
+}
+function modPow(base, exp, mod) {
+    const zero = BigInt(0);
+    const one = BigInt(1);
+    let result = one;
+    base %= mod;
+    while (exp > zero) {
+        if (exp & one)
+            result = (result * base) % mod;
+        base = (base * base) % mod;
+        exp >>= one;
+    }
+    return result;
+}
+/**
+ * Pure-BigInt RSA CRT PKCS#1 v1.5 decryption fallback for Node.js environments
+ * where OpenSSL blocks `RSA_PKCS1_PADDING` in `crypto.privateDecrypt` (CVE-2023-46809).
+ */
+export function rsaDecryptPkcs1Manual(privateKeyPem, cipher) {
+    const jwk = crypto.createPrivateKey(privateKeyPem).export({ format: "jwk" });
+    const n = b64urlToBigInt(jwk.n);
+    const p = b64urlToBigInt(jwk.p);
+    const q = b64urlToBigInt(jwk.q);
+    const dp = b64urlToBigInt(jwk.dp);
+    const dq = b64urlToBigInt(jwk.dq);
+    const qi = b64urlToBigInt(jwk.qi);
+    const c = BigInt("0x" + cipher.toString("hex"));
+    const m1 = modPow(c, dp, p);
+    const m2 = modPow(c, dq, q);
+    const h = (qi * (((m1 - m2) % p) + p)) % p;
+    const m = m2 + h * q;
+    const k = Math.ceil(n.toString(16).length / 2);
+    const em = Buffer.from(m.toString(16).padStart(k * 2, "0"), "hex");
+    if (em[0] !== 0x00 || em[1] !== 0x02)
+        throw new ZaloApiError("Invalid RSA PKCS#1 v1.5 padding");
+    const sep = em.indexOf(0x00, 2);
+    if (sep < 10)
+        throw new ZaloApiError("Invalid RSA PKCS#1 v1.5 padding separator");
+    return em.subarray(sep + 1);
+}
+/**
+ * Decrypt `encrypted_key` from `syncmsg_info` using RSA private key with PKCS#1 v1.5 scheme.
+ * Automatically falls back to pure-BigInt CRT decryption if OpenSSL disables `RSA_PKCS1_PADDING`.
+ */
+export function decryptWithPrivateKey(privateKey, encryptedBase64) {
+    const cleanKey = privateKey.replace(/\\n/g, "\n");
+    const encryptedBuffer = Buffer.from(encryptedBase64, "base64");
+    try {
+        return crypto.privateDecrypt({
+            key: cleanKey,
+            padding: crypto.constants.RSA_PKCS1_PADDING,
+        }, encryptedBuffer);
+    }
+    catch (err) {
+        const errorObj = err;
+        const code = String(errorObj?.code || "");
+        const msg = String(errorObj?.message || "");
+        if (code.includes("INVALID_ARG") || /RSA_PKCS1_PADDING|security-revert|not supported/i.test(msg)) {
+            return rsaDecryptPkcs1Manual(cleanKey, encryptedBuffer);
+        }
+        throw err;
+    }
+}
+/**
+ * Derives the 32-byte AES-256-CBC key for Zalo ZDB4.0 (`.db.crypt`) backup files
+ * from the raw RSA-decrypted bytes: first 32 uppercase hex characters as ASCII bytes.
+ */
+export function deriveZdbAesKey(decryptedRsaBytes) {
+    const upperHex = decryptedRsaBytes.toString("hex").toUpperCase();
+    if (upperHex.length < ZALO_PROTOCOL.AES_256_KEY_BYTE_LENGTH) {
+        throw new ZaloApiError(`Decrypted RSA key hex is too short (${upperHex.length} chars, expected >= 32)`);
+    }
+    return Buffer.from(upperHex.slice(0, ZALO_PROTOCOL.AES_256_KEY_BYTE_LENGTH), "ascii");
+}
+/**
+ * Decrypts a Zalo ZDB4.0 (`.db.crypt`) backup buffer into its plaintext ZDB4.0 container
+ * (header + table of contents + XZ stream) using 64KB independent AES-256-CBC chunks (`IV = 0`).
+ */
+export function decryptZdbBuffer(zdbBuffer, aesKey) {
+    const ZDB_MAGIC = Buffer.from(ZALO_PROTOCOL.ZDB_MAGIC_HEADER, "ascii");
+    const CHUNK_SIZE = ZALO_PROTOCOL.ZDB_CHUNK_SIZE;
+    const zeroIv = Buffer.alloc(16, 0);
+    for (const startOffset of [0, 4]) {
+        const encryptedLength = Math.floor((zdbBuffer.length - startOffset) / 16) * 16;
+        if (encryptedLength < 16)
+            continue;
+        const firstChunkLen = Math.min(CHUNK_SIZE, encryptedLength);
+        const firstDecipher = crypto.createDecipheriv("aes-256-cbc", aesKey, zeroIv);
+        firstDecipher.setAutoPadding(false);
+        const firstPlain = Buffer.concat([
+            firstDecipher.update(zdbBuffer.subarray(startOffset, startOffset + firstChunkLen)),
+            firstDecipher.final(),
+        ]);
+        if (!firstPlain.subarray(0, ZDB_MAGIC.length).equals(ZDB_MAGIC)) {
+            continue;
+        }
+        const chunks = [firstPlain];
+        for (let offset = CHUNK_SIZE; offset < encryptedLength; offset += CHUNK_SIZE) {
+            const len = Math.min(CHUNK_SIZE, encryptedLength - offset);
+            const decipher = crypto.createDecipheriv("aes-256-cbc", aesKey, zeroIv);
+            decipher.setAutoPadding(false);
+            chunks.push(Buffer.concat([
+                decipher.update(zdbBuffer.subarray(startOffset + offset, startOffset + offset + len)),
+                decipher.final(),
+            ]));
+        }
+        return Buffer.concat(chunks);
+    }
+    throw new ZaloApiError("Invalid AES key or buffer is not in ZDB4.0 format");
+}
+/**
+ * Parses the Table of Contents (TOC) from a decrypted ZDB4.0 container buffer,
+ * returning the list of SQLite `.db` files (`<uid>.db` / `group_<gid>.db`) and the byte offset where the XZ stream starts.
+ */
+export function parseZdbHeader(zdbPlaintext) {
+    const ZDB_MAGIC = Buffer.from(ZALO_PROTOCOL.ZDB_MAGIC_HEADER, "ascii");
+    const COUNT_OFFSET = 14;
+    if (zdbPlaintext.length < COUNT_OFFSET + 4 || !zdbPlaintext.subarray(0, ZDB_MAGIC.length).equals(ZDB_MAGIC)) {
+        throw new ZaloApiError("Buffer is not a valid decrypted ZDB4.0 container");
+    }
+    const count = zdbPlaintext.readUInt32BE(COUNT_OFFSET);
+    let offset = COUNT_OFFSET + 4;
+    const entries = [];
+    for (let i = 0; i < count; i++) {
+        if (offset + 4 > zdbPlaintext.length) {
+            throw new ZaloApiError("Truncated ZDB4.0 header while reading entry name length");
+        }
+        const nameLen = zdbPlaintext.readUInt32BE(offset);
+        if (offset + 4 + nameLen + 4 > zdbPlaintext.length) {
+            throw new ZaloApiError("Truncated ZDB4.0 header while reading entry metadata");
+        }
+        const name = zdbPlaintext
+            .toString("utf8", offset + 4, offset + 4 + nameLen)
+            .replace(/\0+$/, "");
+        const size = zdbPlaintext.readUInt32BE(offset + 4 + nameLen);
+        entries.push({ name, size });
+        offset += 4 + nameLen + 4;
+    }
+    return { entries, xzOffset: offset };
+}