minigame-std/dist/types/cryptos.d.ts

Cross-platform standard library for WeChat minigame and web browsers with unified APIs for crypto, fs, fetch, storage, and more.

import { AsyncIOResult } from 'happy-rusty';

/**
 * 公共类型定义模块。
 *
 * @module defines
 */
/**
 * 数据源类型，可以是 string 或者 BufferSource。
 * @since 1.8.0
 * @example
 * ```ts
 * // 字符串类型
 * const strData: DataSource = 'Hello, World!';
 *
 * // ArrayBuffer 类型
 * const bufferData: DataSource = new ArrayBuffer(8);
 *
 * // Uint8Array 类型
 * const u8aData: DataSource = new Uint8Array([1, 2, 3]);
 * ```
 */
type DataSource = string | BufferSource;

/**
 * RSA 公钥接口，用于加密数据。
 * @since 1.6.0
 * @example
 * ```ts
 * import { cryptos } from 'minigame-std';
 *
 * const publicKey = (await cryptos.rsa.importPublicKey(pemString, 'SHA-256')).unwrap();
 *
 * // 加密并返回 ArrayBuffer
 * const encrypted = (await publicKey.encrypt('Hello, World!')).unwrap();
 *
 * // 加密并返回 Base64 字符串
 * const encryptedStr = (await publicKey.encryptToString('Hello, World!')).unwrap();
 * ```
 */
interface RSAPublicKey {
    /**
     * 使用 RSA-OAEP 算法加密数据。
     * @param data - 要加密的数据。
     * @returns 加密后的 ArrayBuffer。
     */
    encrypt(data: DataSource): AsyncIOResult<ArrayBuffer>;
    /**
     * 加密后转换为 Base64 字符串。
     * @param data - 要加密的数据。
     * @returns 加密后的 Base64 字符串。
     */
    encryptToString(data: DataSource): AsyncIOResult<string>;
}
/**
 * RSA-OAEP 加密支持的 SHA 哈希算法。
 *
 * @since 1.6.0
 * @example
 * ```ts
 * import { importPublicKey, type SHA } from 'minigame-std';
 *
 * const hash: SHA = 'SHA-256';
 * const publicKey = (await importPublicKey(pemString, hash)).unwrap();
 * ```
 */
type SHA = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';

/**
 * 使用 SHA-1 算法计算 HMAC。
 * @param key - 密钥，可以是字符串或 BufferSource。
 * @param data - 需要计算 HMAC 的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的 HMAC 字符串。
 * @since 1.8.0
 * @example
 * ```ts
 * const hmac = (await sha1HMAC('secret-key', 'Hello, World!')).unwrap();
 * console.log(hmac); // 十六进制 HMAC 字符串
 * ```
 */
declare function sha1HMAC(key: DataSource, data: DataSource): AsyncIOResult<string>;
/**
 * 使用 SHA-256 算法计算 HMAC。
 * @param key - 密钥，可以是字符串或 BufferSource。
 * @param data - 需要计算 HMAC 的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的 HMAC 字符串。
 * @since 1.8.0
 * @example
 * ```ts
 * const hmac = (await sha256HMAC('secret-key', 'Hello, World!')).unwrap();
 * console.log(hmac); // 十六进制 HMAC 字符串
 * ```
 */
declare function sha256HMAC(key: DataSource, data: DataSource): AsyncIOResult<string>;
/**
 * 使用 SHA-384 算法计算 HMAC。
 * @param key - 密钥，可以是字符串或 BufferSource。
 * @param data - 需要计算 HMAC 的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的 HMAC 字符串。
 * @since 1.8.0
 * @example
 * ```ts
 * const hmac = (await sha384HMAC('secret-key', 'Hello, World!')).unwrap();
 * console.log(hmac); // 十六进制 HMAC 字符串
 * ```
 */
declare function sha384HMAC(key: DataSource, data: DataSource): AsyncIOResult<string>;
/**
 * 使用 SHA-512 算法计算 HMAC。
 * @param key - 密钥，可以是字符串或 BufferSource。
 * @param data - 需要计算 HMAC 的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的 HMAC 字符串。
 * @since 1.8.0
 * @example
 * ```ts
 * const hmac = (await sha512HMAC('secret-key', 'Hello, World!')).unwrap();
 * console.log(hmac); // 十六进制 HMAC 字符串
 * ```
 */
declare function sha512HMAC(key: DataSource, data: DataSource): AsyncIOResult<string>;

/**
 * MD5 哈希计算类，支持流式更新。
 * @since 1.0.0
 * @example
 * ```ts
 * // 基本用法
 * const hash = new Md5().update('Hello, World!').toString();
 * console.log(hash); // '65a8e27d8879283831b664bd8b7f0ad4'
 *
 * // 流式更新
 * const md5 = new Md5();
 * md5.update('Hello, ');
 * md5.update('World!');
 * console.log(md5.toString()); // '65a8e27d8879283831b664bd8b7f0ad4'
 *
 * // 获取 ArrayBuffer
 * const buffer = new Md5().update('test').digest();
 * ```
 */
declare class Md5 {
    private a;
    private b;
    private c;
    private d;
    private block;
    private pos;
    private n0;
    private n1;
    /**
     * 累加已处理的消息长度。
     *
     * n0 和 n1 共同组成一个 64 位计数器，用于记录消息的总字节数。
     * - n0: 低 32 位
     * - n1: 高 32 位
     *
     * 当 n0 溢出（超过 0xffffffff，即 2^32 - 1）时，需要向 n1 进位。
     *
     * @param len - 本次处理的字节数
     */
    private addLength;
    private hash;
    /**
     * 更新内部状态。
     * @param data - 要更新的数据，数据大小不能超过 2^32 字节。
     */
    update(data: DataSource): this;
    /**
     * 返回最终的哈希值。
     */
    digest(): ArrayBuffer;
    /**
     * 以十六进制字符串形式返回哈希值。
     */
    toString(): string;
}

/**
 * 计算字符串或 Buffer 的 MD5 值。
 * @param data - 需要计算 MD5 值的数据，可以是字符串或 BufferSource。
 * @returns 计算得到的 MD5 十六进制字符串（32 位）。
 * @since 1.0.0
 * @example
 * ```ts
 * const hash = md5('Hello, World!');
 * console.log(hash); // '65a8e27d8879283831b664bd8b7f0ad4'
 * ```
 */
declare function md5(data: DataSource): string;

/**
 * UUID 类型。
 * @since 1.7.0
 * @example
 * ```ts
 * import { cryptos, type UUID } from 'minigame-std';
 *
 * const result = await cryptos.randomUUID();
 * if (result.isOk()) {
 *     const uuid: UUID = result.unwrap();
 *     console.log(uuid); // 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
 * }
 * ```
 */
type UUID = `${string}-${string}-${string}-${string}-${string}`;

/**
 * 获取密码学安全的随机数。
 * @param length - 要生成的随机字节数。
 * @returns 包含随机数据的 Uint8Array，封装在 IOResult 中。
 * @since 1.7.0
 * @example
 * ```ts
 * const result = await getRandomValues(16);
 * if (result.isOk()) {
 *     console.log(result.unwrap()); // Uint8Array(16) [...]
 * }
 * ```
 */
declare function getRandomValues(length: number): AsyncIOResult<Uint8Array<ArrayBuffer>>;
/**
 * 生成符合 RFC 4122 标准的 UUID v4。
 * @returns UUID 字符串，封装在 IOResult 中。
 * @since 1.7.0
 * @example
 * ```ts
 * const result = await randomUUID();
 * if (result.isOk()) {
 *     console.log(result.unwrap()); // 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
 * }
 * ```
 */
declare function randomUUID(): AsyncIOResult<UUID>;

/**
 * 从 PEM 格式的字符串导入 RSA 公钥，用于加密操作。
 * @param pem - PEM 格式的公钥字符串。
 * @param hash - 用于 OAEP 填充的哈希算法（SHA-1、SHA-256、SHA-384 或 SHA-512）。
 * @returns RSA 公钥对象，包含 encrypt 方法用于加密数据。
 * @since 1.6.0
 * @example
 * ```ts
 * const publicKey = (await importPublicKey(pemString, 'SHA-256')).unwrap();
 *
 * // 加密并返回 ArrayBuffer
 * const encrypted = (await publicKey.encrypt('Hello, World!')).unwrap();
 *
 * // 加密并返回 Base64 字符串
 * const encryptedStr = (await publicKey.encryptToString('Hello, World!')).unwrap();
 * ```
 */
declare function importPublicKey(pem: string, hash: SHA): AsyncIOResult<RSAPublicKey>;

declare const mod_importPublicKey: typeof importPublicKey;
declare namespace mod {
  export {
    mod_importPublicKey as importPublicKey,
  };
}

/**
 * 计算数据的 SHA-1 哈希值。
 * @param data - 需要计算哈希的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的哈希字符串。
 * @since 1.6.0
 * @example
 * ```ts
 * const hash = await sha1('Hello, World!');
 * if (hash.isOk()) {
 *     console.log(hash.unwrap()); // 十六进制哈希字符串
 * }
 * ```
 */
declare function sha1(data: DataSource): AsyncIOResult<string>;
/**
 * 计算数据的 SHA-256 哈希值。
 * @param data - 需要计算哈希的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的哈希字符串。
 * @since 1.0.0
 * @example
 * ```ts
 * const hash = await sha256('Hello, World!');
 * if (hash.isOk()) {
 *     console.log(hash.unwrap()); // 十六进制哈希字符串
 * }
 * ```
 */
declare function sha256(data: DataSource): AsyncIOResult<string>;
/**
 * 计算数据的 SHA-384 哈希值。
 * @param data - 需要计算哈希的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的哈希字符串。
 * @since 1.6.0
 * @example
 * ```ts
 * const hash = await sha384('Hello, World!');
 * if (hash.isOk()) {
 *     console.log(hash.unwrap()); // 十六进制哈希字符串
 * }
 * ```
 */
declare function sha384(data: DataSource): AsyncIOResult<string>;
/**
 * 计算数据的 SHA-512 哈希值。
 * @param data - 需要计算哈希的数据，可以是字符串或 BufferSource。
 * @returns 返回十六进制格式的哈希字符串。
 * @since 1.6.0
 * @example
 * ```ts
 * const hash = await sha512('Hello, World!');
 * if (hash.isOk()) {
 *     console.log(hash.unwrap()); // 十六进制哈希字符串
 * }
 * ```
 */
declare function sha512(data: DataSource): AsyncIOResult<string>;

export { Md5, getRandomValues, md5, randomUUID, mod as rsa, sha1, sha1HMAC, sha256, sha256HMAC, sha384, sha384HMAC, sha512, sha512HMAC };
export type { RSAPublicKey, SHA, UUID };