wowok 1.8.2 → 2.1.9

package/dist/esm/w/messenger/.eslintrc.js

@@ -0,0 +1,23 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var require_eslintrc = __commonJS({
+  "src/w/messenger/.eslintrc.cjs"(exports, module) {
+    module.exports = {
+      root: false,
+      rules: {
+        // Messenger 模块只在 Node.js 环境中使用，允许使用 Buffer
+        "no-restricted-globals": "off",
+        "@typescript-eslint/ban-types": [
+          "error",
+          {
+            types: {},
+            extendDefaults: true
+          }
+        ]
+      }
+    };
+  }
+});
+export default require_eslintrc();

package/dist/esm/w/messenger/crypto.d.ts

@@ -0,0 +1,269 @@
+import type { Xed25519KeyPair } from "./types.js";
+/**
+ * 从 X25519 私钥恢复 XEd25519 密钥对
+ */
+export declare function recoverXed25519FromX25519PrivateKey(x25519PrivateKey: Uint8Array): Xed25519KeyPair;
+/**
+ * 计算 SHA-256 哈希
+ */
+export declare function hashSha256(data: Uint8Array): Uint8Array;
+/**
+ * 计算消息哈希（用于 Merkle Tree 叶子节点）
+ */
+export declare function hashMessage(data: string): string;
+/**
+ * 计算明文哈希（用于 Merkle Tree 证明）
+ * plaintext_hash = SHA256(plaintext + client_timestamp + guardAddress + passportAddress)
+ */
+export declare function hashPlaintext(plaintext: string, clientTimestamp: number, guardAddress?: string, passportAddress?: string, lastReceivedLeafIndex?: number): string;
+/**
+ * 生成随机 nonce
+ */
+export declare function generateNonce(): string;
+/**
+ * Uint8Array 转 Base64
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Base64 转 Uint8Array
+ */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Uint8Array 转 Hex
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Hex 转 Uint8Array
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * ArrayBuffer 转 Uint8Array
+ */
+export declare function arrayBufferToUint8Array(buf: ArrayBuffer): Uint8Array;
+/**
+ * Uint8Array 转 ArrayBuffer
+ */
+export declare function uint8ArrayToArrayBuffer(arr: Uint8Array): ArrayBuffer;
+/**
+ * 比较两个 ArrayBuffer 是否相等
+ */
+export declare function bufferEqual(a: ArrayBufferLike, b: ArrayBufferLike): boolean;
+/**
+ * 计算 Merkle 叶子哈希（与服务器端 calculate_message_hash 一致）
+ * leaf_hash = SHA256(plaintext_hash.as_bytes() + server_timestamp.to_le_bytes())
+ */
+export declare function calculateMerkleLeafHash(plaintextHash: string, serverTimestamp: number): string;
+/**
+ * 计算两个哈希的父节点哈希
+ */
+export declare function merkleHash(left: string, right: string): string;
+/**
+ * 计算新的 Merkle Root（与服务器保持一致）
+ *
+ * 服务器算法：
+ * new_root = SHA256(prev_root + leaf_hash + leaf_index_le_bytes)
+ *
+ * @param prevRoot 前一个 Root（hex 格式，带或不带 0x 前缀）
+ * @param leafHash 叶子节点哈希（hex 格式，带或不带 0x 前缀）
+ * @param leafIndex 叶子节点索引
+ * @returns 新的 Root（带 0x 前缀的 hex）
+ */
+export declare function computeNewRoot(prevRoot: string, leafHash: string, leafIndex: number): string;
+/**
+ * 验证 Merkle Proof
+ */
+export declare function verifyMerkleProof(leafHash: string, proof: {
+    root: string;
+    siblings: string[];
+    indices: number[];
+}): boolean;
+/**
+ * Merkle Root 链验证结果
+ */
+export interface MerkleChainValidationResult {
+    valid: boolean;
+    error?: string;
+    expectedRoot?: string;
+    actualRoot?: string;
+}
+/**
+ * 验证 Merkle Root 链的完整性和时序性
+ *
+ * 客户端使用此函数独立校验消息链的完整性，通过相同的算法核对 Merkle Tree root 的前后关系
+ *
+ * @param messages 按顺序排列的消息列表（按 leafIndex 排序）
+ * @param initialRoot 初始 Root（可选，默认为全0）
+ * @returns 验证结果
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { leafIndex: 0, prevRoot: "0x00...", newRoot: "0xabc...", plaintextHash: "0x123..." },
+ *   { leafIndex: 1, prevRoot: "0xabc...", newRoot: "0xdef...", plaintextHash: "0x456..." },
+ * ];
+ * const result = verifyMerkleChain(messages);
+ * if (result.valid) {
+ *   console.log("Merkle 链验证通过");
+ * } else {
+ *   console.error("验证失败:", result.error);
+ * }
+ * ```
+ */
+export declare function verifyMerkleChain(messages: Array<{
+    leafIndex: number;
+    prevRoot: string;
+    newRoot: string;
+    plaintextHash: string;
+    serverTimestamp: number;
+}>, initialRoot?: string): MerkleChainValidationResult;
+/**
+ * 验证单个消息的 Merkle Root 计算
+ *
+ * 用于验证服务器返回的 Merkle 数据是否正确
+ *
+ * @param prevRoot 前一个 Root
+ * @param newRoot 新的 Root（服务器返回）
+ * @param plaintextHash 明文哈希
+ * @param serverTimestamp 服务器时间戳
+ * @param leafIndex 叶子索引
+ * @returns 验证结果
+ */
+export declare function verifySingleMerkleRoot(prevRoot: string, newRoot: string, plaintextHash: string, serverTimestamp: number, leafIndex: number): MerkleChainValidationResult;
+/**
+ * 消息验证结果
+ */
+export interface MessageVerificationResult {
+    valid: boolean;
+    error?: string;
+    /** 哪一项验证失败 */
+    failedCheck?: "merkle" | "plaintext";
+}
+/**
+ * 验证消息参数（基于 Message 结构）
+ */
+export interface MessageVerificationParams {
+    /** 消息ID（用于错误信息） */
+    messageId: string;
+    /** 明文内容 */
+    plaintext: string;
+    /** 消息中保存的明文哈希 */
+    plaintextHash: string;
+    /** 消息创建时间（createdAt） */
+    createdAt: number;
+    /** Guard 地址（可选） */
+    guardAddress?: string;
+    /** Passport 地址（可选） */
+    passportAddress?: string;
+    /** 最后收到的消息序号（可选） */
+    lastReceivedLeafIndex?: number;
+    /** 服务器签名（可选） */
+    serverSignature?: string;
+    /** 服务器公钥（可选） */
+    serverPublicKey?: string;
+    /** Merkle 元数据（可选，如果提供则验证 Merkle） */
+    merkleMetadata?: {
+        prevRoot?: string;
+        newRoot: string;
+        /** 服务器时间戳（优先使用 timestamp 字段，兼容 serverTimestamp） */
+        timestamp?: number;
+        serverTimestamp?: number;
+        leafIndex: number;
+        /** Merkle proof siblings（服务器拉取消息时不返回） */
+        proofSiblings?: string[];
+        /** Merkle proof indices（服务器拉取消息时不返回） */
+        proofIndices?: number[];
+    };
+}
+/**
+ * 通用消息验证函数
+ *
+ * 基于 Message 结构中保存的数据验证消息的完整性和 Merkle 证明
+ *
+ * @param params 验证参数
+ * @returns 验证结果
+ *
+ * @example
+ * ```typescript
+ * const result = verifyMessage({
+ *   messageId: "msg-123",
+ *   plaintext: "Hello",
+ *   plaintextHash: "0xabc...",
+ *   createdAt: 1234567890,
+ *   guardAddress: "0x...",
+ *   passportAddress: "0x...",
+ *   merkleMetadata: { ... }
+ * });
+ *
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+export declare function verifyMessage(params: MessageVerificationParams): MessageVerificationResult;
+/**
+ * 验证 Ed25519 签名（十六进制格式）
+ *
+ * @param publicKeyHex 公钥（十六进制字符串）
+ * @param message 消息内容
+ * @param signatureHex 签名（十六进制字符串）
+ * @returns 验证结果
+ */
+export declare function verifyEd25519Signature(publicKeyHex: string, message: string, signatureHex: string): boolean;
+/**
+ * WTS 消息验证参数
+ */
+export interface WtsMessageVerificationParams {
+    /** 消息ID */
+    id: string;
+    /** 发送方地址 */
+    from: string;
+    /** 接收方地址 */
+    to: string;
+    /** 明文哈希 */
+    plaintextHash: string;
+    /** 客户端时间戳 */
+    clientTimestamp: number;
+    /** 服务器时间戳 */
+    timestamp: number;
+    /** 叶子索引 */
+    leafIndex: number;
+    /** Merkle Root */
+    merkleRoot: string;
+    /** 前一个 Merkle Root（可选） */
+    prevRoot?: string;
+    /** 服务器签名 */
+    serverSignature?: string;
+    /** 服务器公钥 */
+    serverPublicKey?: string;
+    /** Guard 地址 */
+    guardAddress?: string;
+    /** Passport 地址 */
+    passportAddress?: string;
+    /** 最后收到的消息序号（可选） */
+    lastReceivedLeafIndex?: number;
+    /** 明文内容（可选，如果提供则验证 plaintextHash） */
+    plaintext?: string;
+    /** Merkle Proof（可选，如果提供则验证 Merkle） */
+    merkleProof?: {
+        siblings: string[];
+        indices: number[];
+    };
+}
+/**
+ * WTS 文件验证结果
+ */
+export interface WtsVerificationResult {
+    valid: boolean;
+    error?: string;
+    /** 验证失败的消息索引 */
+    failedMessageIndex?: number;
+    /** 失败原因 */
+    failedCheck?: "plaintext" | "merkle" | "chain";
+}
+/**
+ * 验证 WTS 文件中的消息
+ *
+ * @param messages WTS 消息列表（按 leafIndex 排序）
+ * @returns 验证结果
+ */
+export declare function verifyWtsMessages(messages: WtsMessageVerificationParams[]): WtsVerificationResult;