@maiyunnet/kebab 2.0.7 → 2.0.8

package/lib/crypto.d.ts

@@ -1,4 +1,14 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-4-2 14:01:06
+ * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47
+ */
 import * as crypto from 'crypto';
+/**
+ * --- 创建非对称秘钥 ---
+ * @param type 如 rsa/ec
+ * @param options 参数
+ */
 export declare function generateKeyPair(type: string, options?: {
     'modulusLength'?: number;
     'namedCurve'?: string;
@@ -16,32 +26,91 @@ export declare function generateKeyPair(type: string, options?: {
 }>;
 export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format: 'hex' | 'base64' | 'binary', algorithm?: string): string;
 export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format?: 'buffer', algorithm?: string): Buffer;
+/**
+ * --- 非对称验签 ---
+ * @param data 数据
+ * @param object 证书
+ * @param signature 签名
+ * @param algorithm 哈希方式
+ */
 export declare function verify(data: crypto.BinaryLike, object: crypto.KeyLike | crypto.VerifyKeyObjectInput | crypto.VerifyPublicKeyInput | crypto.VerifyJsonWebKeyInput, signature: NodeJS.ArrayBufferView, algorithm?: string): boolean;
+/**
+ * --- 非对称公钥加密 ---
+ * @param key 公钥
+ * @param buffer 数据
+ */
 export declare function publicEncrypt(key: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
+/**
+ * --- 非对称私钥加密 ---
+ * @param key 私钥
+ * @param buffer 数据
+ */
 export declare function privateEncrypt(key: crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
+/**
+ * --- 非对称公钥解密 ---
+ * @param key 公钥
+ * @param buffer 数据
+ */
 export declare function publicDecrypt(key: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
+/**
+ * --- 非对称私钥解密 ---
+ * @param key 私钥
+ * @param buffer 数据
+ */
 export declare function privateDecrypt(key: crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView): Buffer;
-export declare const AES_256_ECB = "AES-256-ECB";
-export declare const AES_256_CBC = "AES-256-CBC";
-export declare const AES_256_CFB = "AES-256-CFB";
-export declare const SM4_ECB = "SM4-ECB";
-export declare const SM4_CBC = "SM4-CBC";
-export declare const SM4_CFB = "SM4-CFB";
+export declare const AES_256_ECB = "aes-256-ecb";
+export declare const AES_256_CBC = "aes-256-cbc";
+export declare const AES_256_CFB = "aes-256-cfb";
+export declare const AES_256_GCM = "aes-256-gcm";
+export declare const SM4_ECB = "sm4-ecb";
+export declare const SM4_CBC = "sm4-cbc";
+export declare const SM4_CFB = "sm4-cfb";
+/**
+ * --- cipher 加密，强烈不建议使用 AES_256_ECB ---
+ * @param original 原始字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16(CFB) 或 12(GCM) 个英文字母和数字
+ * @param method 加密方法
+ */
 export declare function cipherEncrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64' | 'buffer'): string | Buffer | false;
 export declare function aesEncrypt(original: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
 export declare function aesEncrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64'): string | false;
+export declare function gcmEncrypt(original: string | Buffer, key: crypto.CipherKey, output: 'buffer'): Buffer | false;
+export declare function gcmEncrypt(original: string | Buffer, key: crypto.CipherKey, output?: 'base64'): string | false;
 export declare function sm4Encrypt(original: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
 export declare function sm4Encrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64'): string | false;
+/**
+ * --- cipher 解密 ---
+ * @param encrypt 需解密的字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16(CFB) 或 12(GCM) 个英文字母和数字
+ * @param method 加密方法
+ */
 export declare function cipherDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary' | 'buffer'): string | Buffer | false;
 export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
 export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary'): string | false;
+export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, output: 'buffer'): Buffer | false;
+export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, output?: 'binary'): string | false;
 export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
 export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary'): string | false;
 export declare function hashHmac(algorithm: string, data: Buffer | string, key?: crypto.CipherKey, format?: 'hex' | 'base64'): string;
 export declare function hashHmac(algorithm: string, data: Buffer | string, key: crypto.CipherKey | undefined, format: 'buffer'): Buffer;
 export declare function hashHmacFile(algorithm: string, path: string, key?: crypto.CipherKey, encoding?: 'hex' | 'base64' | 'base64url'): Promise<string | false>;
 export declare function hashHmacFile(algorithm: string, path: string, key: crypto.CipherKey, encoding: 'buffer'): Promise<Buffer | false>;
+/**
+ * --- base64 编码 ---
+ * @param data 字符串或 Buffer
+ */
 export declare function base64Encode(data: string | Buffer): string;
+/**
+ * --- base64 解码 ---
+ * @param data base64 编码的字符串
+ * @param encoding 指定解出 Buffer 还是 string ---
+ */
 export declare function base64Decode(data: string, encoding: 'buffer'): Buffer;
 export declare function base64Decode(data: string, encoding?: 'utf8'): string;
+/**
+ * --- 生成 uuid ---
+ * @param options 选项
+ */
 export declare function uuid(options?: crypto.RandomUUIDOptions): string;

package/lib/crypto.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SM4_CFB = exports.SM4_CBC = exports.SM4_ECB = exports.AES_256_CFB = exports.AES_256_CBC = exports.AES_256_ECB = void 0;
+exports.SM4_CFB = exports.SM4_CBC = exports.SM4_ECB = exports.AES_256_GCM = exports.AES_256_CFB = exports.AES_256_CBC = exports.AES_256_ECB = void 0;
 exports.generateKeyPair = generateKeyPair;
 exports.sign = sign;
 exports.verify = verify;
@@ -43,49 +43,50 @@ exports.publicDecrypt = publicDecrypt;
 exports.privateDecrypt = privateDecrypt;
 exports.cipherEncrypt = cipherEncrypt;
 exports.aesEncrypt = aesEncrypt;
+exports.gcmEncrypt = gcmEncrypt;
 exports.sm4Encrypt = sm4Encrypt;
 exports.cipherDecrypt = cipherDecrypt;
 exports.aesDecrypt = aesDecrypt;
+exports.gcmDecrypt = gcmDecrypt;
 exports.sm4Decrypt = sm4Decrypt;
 exports.hashHmac = hashHmac;
 exports.hashHmacFile = hashHmacFile;
 exports.base64Encode = base64Encode;
 exports.base64Decode = base64Decode;
 exports.uuid = uuid;
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-4-2 14:01:06
+ * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47
+ */
 const crypto = __importStar(require("crypto"));
-const fs = __importStar(require("../lib/fs"));
+// --- 库和定义 ---
+const lFs = __importStar(require("../lib/fs"));
+const lCore = __importStar(require("../lib/core"));
+// --- 非对称加密 ---
+/**
+ * --- 创建非对称秘钥 ---
+ * @param type 如 rsa/ec
+ * @param options 参数
+ */
 function generateKeyPair(type, options = {}) {
     return new Promise((resolve) => {
-        if (options.modulusLength === undefined) {
-            options.modulusLength = 2048;
-        }
+        options.modulusLength ??= 2048;
         if (options.namedCurve !== undefined) {
             options.namedCurve = options.namedCurve.toUpperCase();
         }
-        if (options.publicKeyEncoding === undefined) {
-            options.publicKeyEncoding = {
-                'format': 'pem',
-                'type': 'spki'
-            };
-        }
-        if (options.publicKeyEncoding.type === undefined) {
-            options.publicKeyEncoding.type = 'spki';
-        }
-        if (options.publicKeyEncoding.format === undefined) {
-            options.publicKeyEncoding.format = 'pem';
-        }
-        if (options.privateKeyEncoding === undefined) {
-            options.privateKeyEncoding = {
-                'format': 'pem',
-                'type': 'pkcs8'
-            };
-        }
-        if (options.privateKeyEncoding.type === undefined) {
-            options.privateKeyEncoding.type = 'pkcs8';
-        }
-        if (options.privateKeyEncoding.format === undefined) {
-            options.privateKeyEncoding.format = 'pem';
-        }
+        options.publicKeyEncoding ??= {
+            'format': 'pem',
+            'type': 'spki'
+        };
+        options.publicKeyEncoding.type ??= 'spki';
+        options.publicKeyEncoding.format ??= 'pem';
+        options.privateKeyEncoding ??= {
+            'format': 'pem',
+            'type': 'pkcs8'
+        };
+        options.privateKeyEncoding.type ??= 'pkcs8';
+        options.privateKeyEncoding.format ??= 'pem';
         crypto.generateKeyPair(type, options, (err, publicKey, privateKey) => {
             resolve({
                 'private': privateKey,
@@ -94,42 +95,98 @@ function generateKeyPair(type, options = {}) {
         });
     });
 }
+/**
+ * --- 非对称加签 ---
+ * @param data 数据
+ * @param privateKey 私钥
+ * @param format 输出格式
+ * @param algorithm 哈希方式
+ */
 function sign(data, privateKey, format = 'buffer', algorithm = 'sha256') {
     const sign = crypto.createSign(algorithm);
     sign.update(data);
     return format === 'buffer' ? sign.sign(privateKey) : sign.sign(privateKey, format);
 }
+/**
+ * --- 非对称验签 ---
+ * @param data 数据
+ * @param object 证书
+ * @param signature 签名
+ * @param algorithm 哈希方式
+ */
 function verify(data, object, signature, algorithm = 'sha256') {
     const verify = crypto.createVerify(algorithm);
     verify.update(data);
     return verify.verify(object, signature);
 }
+/**
+ * --- 非对称公钥加密 ---
+ * @param key 公钥
+ * @param buffer 数据
+ */
 function publicEncrypt(key, buffer) {
     return crypto.publicEncrypt(key, buffer);
 }
+/**
+ * --- 非对称私钥加密 ---
+ * @param key 私钥
+ * @param buffer 数据
+ */
 function privateEncrypt(key, buffer) {
     return crypto.privateEncrypt(key, buffer);
 }
+/**
+ * --- 非对称公钥解密 ---
+ * @param key 公钥
+ * @param buffer 数据
+ */
 function publicDecrypt(key, buffer) {
     return crypto.publicDecrypt(key, buffer);
 }
+/**
+ * --- 非对称私钥解密 ---
+ * @param key 私钥
+ * @param buffer 数据
+ */
 function privateDecrypt(key, buffer) {
     return crypto.privateDecrypt(key, buffer);
 }
-exports.AES_256_ECB = 'AES-256-ECB';
-exports.AES_256_CBC = 'AES-256-CBC';
-exports.AES_256_CFB = 'AES-256-CFB';
-exports.SM4_ECB = 'SM4-ECB';
-exports.SM4_CBC = 'SM4-CBC';
-exports.SM4_CFB = 'SM4-CFB';
+// --- Cipher (AES/SM4...) 加/解密 ---
+exports.AES_256_ECB = 'aes-256-ecb'; // --- 如果未设置 iv，则默认这个，但强烈不建议 ---
+exports.AES_256_CBC = 'aes-256-cbc';
+exports.AES_256_CFB = 'aes-256-cfb'; // --- 设置 iv，自动就切换成了这个 ---
+exports.AES_256_GCM = 'aes-256-gcm'; // --- 强烈建议使用这个 ---
+exports.SM4_ECB = 'sm4-ecb'; // --- SM4 如果未设置 iv，则默认这个 ---
+exports.SM4_CBC = 'sm4-cbc';
+exports.SM4_CFB = 'sm4-cfb'; // --- SM4 一般用这个，设置 iv，自动就切换成了这个 ---
+/**
+ * --- cipher 加密，强烈不建议使用 AES_256_ECB ---
+ * @param original 原始字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16(CFB) 或 12(GCM) 个英文字母和数字
+ * @param method 加密方法
+ */
 function cipherEncrypt(original, key, iv = '', method = exports.AES_256_ECB, output = 'base64') {
     try {
-        if (typeof key === 'string' && key.length < 32) {
+        if ((typeof key === 'string') && (key.length !== 32)) {
             key = hashHmac('md5', key, 'MaiyunSalt');
         }
+        if (iv) {
+            if (method === exports.AES_256_CFB) {
+                if (iv.length !== 16) {
+                    return false;
+                }
+            }
+            else if (method === exports.AES_256_GCM) {
+                if (iv.length !== 12) {
+                    return false;
+                }
+            }
+        }
         const cip = crypto.createCipheriv(method, key, iv);
         let r;
         if (output !== 'buffer') {
+            // --- base64 ---
             if (typeof original === 'string') {
                 r = cip.update(original, 'utf8', 'base64');
             }
@@ -137,8 +194,12 @@ function cipherEncrypt(original, key, iv = '', method = exports.AES_256_ECB, out
                 r = cip.update(original, undefined, 'base64');
             }
             r += cip.final('base64');
+            if (method === exports.AES_256_GCM) {
+                r += cip.getAuthTag().toString('hex');
+            }
         }
         else {
+            // --- buffer ---
             if (typeof original === 'string') {
                 r = cip.update(original, 'utf8');
             }
@@ -146,6 +207,9 @@ function cipherEncrypt(original, key, iv = '', method = exports.AES_256_ECB, out
                 r = cip.update(original);
             }
             r = Buffer.concat([r, cip.final()]);
+            if (method === exports.AES_256_GCM) {
+                r = Buffer.concat([r, cip.getAuthTag()]);
+            }
         }
         return r;
     }
@@ -153,26 +217,85 @@ function cipherEncrypt(original, key, iv = '', method = exports.AES_256_ECB, out
         return false;
     }
 }
+/**
+ * --- AES 加密 ---
+ * @param original 原始字符串
+ * @param key 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
+ * @param iv 向量 16 个英文字母和数字
+ * @param method 加密方法
+ * @param output 输出类型
+ */
 function aesEncrypt(original, key, iv = '', method = exports.AES_256_ECB, output = 'base64') {
     if (iv !== '') {
         method = method === exports.AES_256_ECB ? exports.AES_256_CFB : method;
     }
     return cipherEncrypt(original, key, iv, method, output);
 }
+/**
+ * --- AES GCM 托管加密 ---
+ * @param original 原始字符串
+ * @param key 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
+ * @param output 输出类型
+ */
+function gcmEncrypt(original, key, output = 'base64') {
+    const iv = lCore.random(12, lCore.RANDOM_LUNS);
+    const rtn = cipherEncrypt(original, key, iv, exports.AES_256_GCM, output);
+    if (!rtn) {
+        return false;
+    }
+    return typeof rtn === 'string' ? iv + rtn : Buffer.concat([Buffer.from(iv), rtn]);
+}
+/**
+ * --- SM4 加密 ---
+ * @param original 原始字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16 个英文字母和数字
+ * @param method 加密方法
+ */
 function sm4Encrypt(original, key, iv = '', method = exports.SM4_ECB, output = 'base64') {
     if (iv !== '') {
         method = method === exports.SM4_ECB ? exports.SM4_CFB : method;
     }
     return cipherEncrypt(original, key, iv, method, output);
 }
+/**
+ * --- cipher 解密 ---
+ * @param encrypt 需解密的字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16(CFB) 或 12(GCM) 个英文字母和数字
+ * @param method 加密方法
+ */
 function cipherDecrypt(encrypt, key, iv = '', method = exports.AES_256_ECB, output = 'binary') {
     try {
-        if (typeof key === 'string' && key.length < 32) {
+        if ((typeof key === 'string') && (key.length !== 32)) {
             key = hashHmac('md5', key, 'MaiyunSalt');
         }
+        if (iv) {
+            if (method === exports.AES_256_CFB) {
+                if (iv.length !== 16) {
+                    return false;
+                }
+            }
+            else if (method === exports.AES_256_GCM) {
+                if (iv.length !== 12) {
+                    return false;
+                }
+            }
+        }
         const cip = crypto.createDecipheriv(method, key, iv);
+        if (method === exports.AES_256_GCM) {
+            if (typeof encrypt === 'string') {
+                cip.setAuthTag(Buffer.from(encrypt.slice(-32), 'hex'));
+                encrypt = encrypt.slice(0, -32);
+            }
+            else {
+                cip.setAuthTag(encrypt.subarray(-16));
+                encrypt = encrypt.subarray(0, -16);
+            }
+        }
         let r;
         if (output !== 'buffer') {
+            // --- base64 ---
             if (typeof encrypt === 'string') {
                 r = cip.update(encrypt, 'base64', 'binary');
             }
@@ -182,6 +305,7 @@ function cipherDecrypt(encrypt, key, iv = '', method = exports.AES_256_ECB, outp
             r += cip.final('binary');
         }
         else {
+            // --- buffer ---
             if (typeof encrypt === 'string') {
                 r = cip.update(encrypt, 'base64');
             }
@@ -196,18 +320,48 @@ function cipherDecrypt(encrypt, key, iv = '', method = exports.AES_256_ECB, outp
         return false;
     }
 }
+/**
+ * --- AES 解密 ---
+ * @param encrypt 需解密的字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16 个英文字母和数字
+ * @param method 加密方法
+ */
 function aesDecrypt(encrypt, key, iv = '', method = exports.AES_256_ECB, output = 'binary') {
     if (iv !== '') {
         method = method === exports.AES_256_ECB ? exports.AES_256_CFB : method;
     }
     return cipherDecrypt(encrypt, key, iv, method, output);
 }
+/**
+ * --- AES 解密 ---
+ * @param encrypt 需解密的字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16 个英文字母和数字
+ * @param method 加密方法
+ */
+function gcmDecrypt(encrypt, key, output = 'binary') {
+    return cipherDecrypt(typeof encrypt === 'string' ? encrypt.slice(12) : encrypt.subarray(12), key, typeof encrypt === 'string' ? encrypt.slice(0, 12) : encrypt.subarray(0, 12).toString(), exports.AES_256_GCM, output);
+}
+/**
+ * --- SM4 解密 ---
+ * @param encrypt 需解密的字符串
+ * @param key 密钥 32 个英文字母和数字
+ * @param iv 向量 16 个英文字母和数字
+ * @param method 加密方法
+ */
 function sm4Decrypt(encrypt, key, iv = '', method = exports.SM4_ECB, output = 'binary') {
     if (iv !== '') {
         method = method === exports.SM4_ECB ? exports.SM4_CFB : method;
     }
     return cipherDecrypt(encrypt, key, iv, method, output);
 }
+/**
+ * --- hash 或 hmac 加密 ---
+ * @param algorithm 哈希方式
+ * @param data 源数据
+ * @param key 设置则采用 hmac 加密
+ */
 function hashHmac(algorithm, data, key, format = 'hex') {
     const cry = key ? crypto.createHmac(algorithm, key) : crypto.createHash(algorithm);
     cry.update(data);
@@ -218,10 +372,16 @@ function hashHmac(algorithm, data, key, format = 'hex') {
         return cry.digest(format);
     }
 }
+/**
+ * --- hash 或 hmac 加密文件 ---
+ * @param algorithm 加密方式，如 md5、sha256、sm3 等
+ * @param path 文件路径
+ * @param key 设置则采用 hmac 加密
+ */
 function hashHmacFile(algorithm, path, key, encoding = 'hex') {
     return new Promise(function (resolve) {
         const cry = key ? crypto.createHmac(algorithm, key) : crypto.createHash(algorithm);
-        const rs = fs.createReadStream(path);
+        const rs = lFs.createReadStream(path);
         rs.on('data', (chunk) => {
             cry.update(chunk);
         }).on('end', function () {
@@ -236,6 +396,10 @@ function hashHmacFile(algorithm, path, key, encoding = 'hex') {
         });
     });
 }
+/**
+ * --- base64 编码 ---
+ * @param data 字符串或 Buffer
+ */
 function base64Encode(data) {
     if (typeof data === 'string') {
         return Buffer.from(data, 'utf8').toString('base64');
@@ -251,6 +415,10 @@ function base64Decode(data, encoding = 'utf8') {
     }
     return buffer.toString('utf8');
 }
+/**
+ * --- 生成 uuid ---
+ * @param options 选项
+ */
 function uuid(options) {
     return crypto.randomUUID(options);
 }