wowok 2.1.39 → 2.1.41

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

@@ -1,121 +1,30 @@
 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 + lastReceivedLeafIndex + client_timestamp + guardAddress + passportAddress)
- *
- * 【注意】顺序必须与服务器端一致：
- * 1. plaintext
- * 2. lastReceivedLeafIndex (if >= 0)
- * 3. clientTimestamp
- * 4. guardAddress (if present)
- * 5. passportAddress (if present)
- */
 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;
@@ -123,154 +32,59 @@ export declare function verifyMerkleChain(messages: Array<{
     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;