wowok 1.8.2 → 2.1.9

package/dist/cjs/w/messenger/types.d.ts

@@ -0,0 +1,705 @@
+import { ENTRYPOINT } from "../../client/network.js";
+import type { SignatureScheme } from "../../cryptography/signature-scheme.js";
+import type { AccountOrMark_Address } from "../local/index.js";
+/**
+ * Messenger 核心类型定义
+ *
+ * 三重信任模型：
+ * 1. 身份信任：基于 wowok 账户体系的 Ed25519 签名验证
+ * 2. 加密信任：基于 Signal Protocol 双棘轮算法的端到端加密
+ * 3. 时序信任：基于 Merkle Tree + 服务器签名 + 链上证明
+ */
+export declare enum MessageType {
+    PREKEY_MESSAGE = 3,// 首次建立会话的预密钥消息
+    NORMAL_MESSAGE = 1
+}
+export declare enum MessageDirection {
+    SENT = "sent",
+    RECEIVED = "received"
+}
+export declare enum MessageStatus {
+    PENDING = "pending",// 已提交服务器，等待确认
+    CONFIRMED = "confirmed",// 已纳入 Merkle Tree
+    READ = "read",// 接收方已确认（ARK）
+    FAILED = "failed",// 发送/处理失败
+    REJECTED = "rejected"
+}
+/**
+ * 明文消息内容结构
+ * 包含实际消息内容和消息确认信息
+ */
+export interface PlaintextMessage {
+    /** 实际消息内容 */
+    content: string;
+    /** 最后收到的消息 leafIndex（用于消息同步确认） */
+    lastReceivedLeafIndex: number;
+    /** 消息创建时间戳（客户端时间，毫秒） */
+    createdAt: number;
+    /** Guard 地址（可选） */
+    guardAddress?: string;
+    /** Passport 地址（可选） */
+    passportAddress?: string;
+}
+export interface Message {
+    messageId: string;
+    fromAddress: string;
+    toAddress: string;
+    plaintextHash: string;
+    plaintext?: string;
+    guardAddress?: string;
+    passportAddress?: string;
+    lastReceivedLeafIndex?: number;
+    direction: MessageDirection;
+    status: MessageStatus;
+    msgType: MessageType.PREKEY_MESSAGE | MessageType.NORMAL_MESSAGE;
+    leafIndex?: number;
+    prevRoot?: string;
+    newRoot?: string;
+    serverSignature?: string;
+    serverTimestamp?: number;
+    serverPublicKey?: string;
+    arkConfirmed?: {
+        recipient: string;
+        recipientPublicKey: string;
+        signature: string;
+        timestamp: number;
+    };
+    createdAt: number;
+    receivedAt?: number;
+    zipMetadata?: ZipMetadata;
+    proof?: string;
+}
+export type ZipContentType = "wts" | "wip" | "zip";
+export interface ZipMetadata {
+    fileName: string;
+    fileSize: number;
+    fileHash: string;
+    contentType: ZipContentType;
+    localCachePath?: string;
+    downloadedAt?: number;
+}
+export interface MerkleProof {
+    root: string;
+    leafIndex: number;
+    siblings: string[];
+    indices: number[];
+}
+export interface MerkleMetadata {
+    leafIndex: number;
+    leafHash: string;
+    /** 当前 Merkle Root (服务器返回的字段名) */
+    newRoot: string;
+    proofSiblings: string[];
+    proofIndices: number[];
+    /** 前一个 Merkle Root (服务器返回的字段名) */
+    prevRoot: string;
+    /** 服务器时间戳（服务器返回的字段名） */
+    serverTimestamp: number;
+    serverSignature?: string;
+    serverPublicKey?: string;
+}
+export interface SessionState {
+    sessionId: string;
+    myAddress: string;
+    peerAddress: string;
+    currentRoot: string;
+    prevRoot: string;
+    messageCount: number;
+    lastLeafIndex: number;
+    lastConfirmedHash: string;
+    lastSyncAt: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ServerRegisterRequest {
+    userAddress: string;
+    deviceId: number;
+    registrationId: number;
+    identityKey: string;
+    prekeys: PreKeyPublic[];
+    publicKey: string;
+    signatureScheme: SignatureScheme;
+    signature: string;
+    timestamp: number;
+    nonce: string;
+}
+export interface PreKeyPublic {
+    keyId: number;
+    publicKey: string;
+    signature: string;
+}
+export interface ServerRegisterResponse {
+    success: boolean;
+    uploadedCount: number;
+    failedPrekeys: FailedPrekeyInfo[];
+    currentTotal: number;
+    maxAllowed: number;
+}
+export interface FailedPrekeyInfo {
+    keyId: number;
+    reason: string;
+}
+export interface UploadPreKeysRequest {
+    userAddress: string;
+    prekeys: PreKeyPublic[];
+    publicKey: string;
+    signatureScheme: SignatureScheme;
+    signature: string;
+    timestamp: number;
+    nonce: string;
+}
+export interface UploadPreKeysResponse {
+    success: boolean;
+    uploadedCount: number;
+    failedPrekeys: FailedPrekeyInfo[];
+    currentTotal: number;
+    maxAllowed: number;
+}
+export interface RemoteBundle {
+    registrationId: number;
+    identityKey: string;
+    signedPrekey?: {
+        keyId: number;
+        publicKey: string;
+        signature: string;
+    };
+}
+export interface SendMessageRequest {
+    sender: string;
+    recipient: string;
+    ciphertext: string;
+    plaintextHash: string;
+    clientTimestamp: number;
+    msgType: MessageType.PREKEY_MESSAGE | MessageType.NORMAL_MESSAGE;
+    zipMetadata?: ZipMetadata;
+    guardAddress?: string;
+    passportAddress?: string;
+    lastReceivedLeafIndex?: number;
+    signatureScheme?: SignatureScheme;
+    signature?: string;
+    timestamp?: number;
+    nonce?: string;
+    force?: boolean;
+}
+export interface SendMessageResponse {
+    messageId: string;
+    status: "confirmed" | "pending";
+    merkleData?: {
+        leafIndex: number;
+        prevRoot: string;
+        newRoot: string;
+        serverSignature: string;
+        serverTimestamp: number;
+        serverPublicKey: string;
+    };
+    /**
+     * 方案B：会话中其他已验证消息的 Merkle 数据
+     * 当发送方发送新消息时，服务器返回会话中其他已验证但发送方可能缺少 Merkle 数据的消息
+     * 键为消息ID，值为Merkle数据
+     */
+    pendingMerkleData?: Record<string, {
+        leafIndex: number;
+        leafHash: string;
+        prevRoot: string;
+        newRoot: string;
+        serverSignature: string;
+        serverTimestamp: number;
+        serverPublicKey: string;
+    }>;
+}
+export interface PullMessagesResponse {
+    messages: ServerMessage[];
+}
+export interface PreKeyStatus {
+    currentCount: number;
+    maxAllowed: number;
+    threshold: number;
+    shouldRefill: boolean;
+}
+export interface ServerMessage {
+    id: string;
+    from: string;
+    to: string;
+    bodyB64: string;
+    plaintextHash?: string;
+    clientTimestamp?: number;
+    msgType: number;
+    registrationId?: number;
+    merkleMetadata?: MerkleMetadata;
+    zipMetadata?: ZipMetadata;
+    guardAddress?: string;
+    passportAddress?: string;
+    lastReceivedLeafIndex?: number;
+}
+export interface ChainProofRequest {
+    merkleRoot: string;
+    sessionId: string;
+    messageCount: number;
+}
+export interface ChainProofResponse {
+    proofAddress: string;
+    txHash: string;
+    blockHeight: number;
+    blockTimestamp: number;
+}
+export declare const WTS_FILE_BYTES_LIMIT: number;
+export declare const WTS_MAX_MESSAGE_COUNT = 1000;
+export declare const NORMAL_MESSAGE_BYTES_LIMIT: number;
+export declare const DEFAULT_QUERY_LIMIT = 50;
+export declare const MAX_QUERY_LIMIT = 1000;
+export declare const DEFAULT_DEVICE_ID = 1;
+export declare const SERVER_URL = "https://messenger.wowok.net";
+export declare const CHAIN_PROOF_TYPE = 1;
+export declare const CURRENT_NETWORK = ENTRYPOINT.Testnet;
+export interface MessengerConfig {
+    prekey_count: number;
+    watch_interval_ms: number;
+    serverUrl?: string;
+    network?: ENTRYPOINT;
+    prekeyCheckIntervalMs?: number;
+    defaultQueryLimit?: number;
+}
+export declare const DEFAULT_MESSENGER_CONFIG: MessengerConfig;
+export interface SignedRequestBase {
+    publicKey: string;
+    signatureScheme: SignatureScheme;
+    signature: string;
+    timestamp: number;
+    nonce: string;
+}
+export interface FetchMessagesRequest extends SignedRequestBase {
+    limit?: number;
+}
+export interface EventStreamParams extends SignedRequestBase {
+}
+export interface GetBundleParams extends SignedRequestBase {
+}
+export type SseEventType = "NewMessage" | "PreKeyLow" | "Custom" | "ark_confirmed" | "guard_confirmed" | "guard_rejected";
+export interface SseNewMessageEvent {
+    type: "NewMessage";
+}
+export interface SseArkConfirmedEvent {
+    type: "ark_confirmed";
+    data: {
+        message_ids: string[];
+        recipient: string;
+        recipient_public_key: string;
+        signature: string;
+        timestamp: number;
+    };
+}
+export interface SsePreKeyLowEvent {
+    type: "PreKeyLow";
+    data: {
+        current: number;
+        threshold: number;
+        max_allowed: number;
+    };
+}
+export interface SseCustomEvent {
+    type: "Custom";
+    data: string;
+}
+export interface SseGuardConfirmedEvent {
+    type: "guard_confirmed";
+    data: {
+        message_id: string;
+        merkle_data: {
+            leafIndex: number;
+            leafHash: string;
+            prevRoot: string;
+            newRoot: string;
+            serverSignature: string;
+            serverTimestamp: number;
+            serverPublicKey: string;
+        };
+        timestamp: number;
+    };
+}
+export interface SseGuardRejectedEvent {
+    type: "guard_rejected";
+    data: {
+        message_id: string;
+        reason: string;
+        timestamp: number;
+    };
+}
+export type SseEvent = SseNewMessageEvent | SseArkConfirmedEvent | SsePreKeyLowEvent | SseCustomEvent | SseGuardConfirmedEvent | SseGuardRejectedEvent;
+export interface SendMessageResult {
+    messageId: string;
+    status: MessageStatus;
+    merkleData?: {
+        leafIndex: number;
+        prevRoot: string;
+        newRoot: string;
+        serverSignature: string;
+        serverTimestamp: number;
+        serverPublicKey: string;
+    };
+    guardList?: string[];
+}
+export interface DecryptedMessage {
+    id: string;
+    from: string;
+    plaintext: string;
+    timestamp: number;
+    merkleVerified: boolean;
+    merkleData?: {
+        leafIndex: number;
+        rootHash: string;
+    };
+}
+export interface Xed25519KeyPair {
+    x25519PublicKey: Uint8Array;
+    x25519PrivateKey: Uint8Array;
+    ed25519PublicKey: Uint8Array;
+    ed25519PrivateKey: Uint8Array;
+}
+export interface Empty {
+}
+export interface SignedRequest<T> {
+    userAddress: string;
+    publicKey: string;
+    signatureScheme: SignatureScheme;
+    signature: string;
+    timestamp: number;
+    nonce: string;
+    data: T;
+}
+export declare enum MessengerErrorCode {
+    PREKEYS_FULL = "PREKEYS_FULL",
+    ACCOUNT_NOT_FOUND = "ACCOUNT_NOT_FOUND",
+    IDENTITY_NOT_FOUND = "IDENTITY_NOT_FOUND",
+    IDENTITY_CONFLICT = "IDENTITY_CONFLICT",
+    SESSION_NOT_ESTABLISHED = "SESSION_NOT_ESTABLISHED",
+    ENCRYPTION_FAILED = "ENCRYPTION_FAILED",
+    DECRYPTION_FAILED = "DECRYPTION_FAILED",
+    SERVER_ERROR = "SERVER_ERROR",
+    INVALID_PROOF = "INVALID_PROOF",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    INVALID_INPUT = "INVALID_INPUT",
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    INVALID_MESSAGE_TYPE = "INVALID_MESSAGE_TYPE",
+    MESSAGE_NOT_DECRYPTED = "MESSAGE_NOT_DECRYPTED",
+    HASH_MISMATCH = "HASH_MISMATCH",
+    ACCOUNT_MESSENGER_NOT_ENABLED = "ACCOUNT_MESSENGER_NOT_ENABLED"
+}
+/**
+ * 消息过滤条件
+ *
+ * 所有条件都是可选的，默认返回当前用户的所有消息
+ */
+/** 时间字段类型 */
+export type MessageTimeField = "createdAt" | "receivedAt" | "serverTimestamp";
+/**
+ * 消息内容类型（用于过滤）
+ * - "text": 普通文本消息
+ * - "zip": ZIP 压缩文件消息
+ * - "wts": WTS 文件消息
+ * - "wip": WIP 文件消息
+ */
+export type MessageContentType = "text" | "zip" | "wts" | "wip";
+export interface MessageFilter {
+    /** 按消息方向过滤 */
+    direction?: MessageDirection;
+    /** 按消息状态过滤 */
+    status?: MessageStatus;
+    /** 按会话过滤（对方地址） */
+    peerAddress?: AccountOrMark_Address;
+    /** 按消息类型过滤（使用 MessageType 枚举） */
+    msgType?: MessageType;
+    /** 按内容类型过滤（更友好的方式） */
+    contentType?: MessageContentType;
+    /** 只返回已解密的消息 */
+    decryptedOnly?: boolean;
+    /** 只返回已确认的消息（已纳入 Merkle Tree） */
+    confirmedOnly?: boolean;
+    /** 关键词搜索（在明文中搜索） */
+    keyword?: string;
+    /** 排序方式：asc = 正序（旧到新），desc = 倒序（新到旧） */
+    sortOrder?: "asc" | "desc";
+    /** 返回数量限制 */
+    limit?: number;
+    /** 分页偏移量 */
+    offset?: number;
+    /** 用于时间过滤的时间字段，默认为 "createdAt" */
+    timeField?: MessageTimeField;
+    /** 开始时间戳（毫秒） */
+    startTime?: number;
+    /** 结束时间戳（毫秒） */
+    endTime?: number;
+    /** 按创建时间过滤（客户端发送时间） */
+    createdAtStart?: number;
+    createdAtEnd?: number;
+    /** 按本地接收时间过滤 */
+    receivedAtStart?: number;
+    receivedAtEnd?: number;
+    /** 按服务器确认时间过滤 */
+    serverTimestampStart?: number;
+    serverTimestampEnd?: number;
+    /** 只返回已收到 ARK 确认的消息 */
+    arkConfirmedOnly?: boolean;
+    /** 按 ARK 确认时间过滤 */
+    arkTimestampStart?: number;
+    arkTimestampEnd?: number;
+    /** 只返回已设置 proof 的消息 */
+    proofedOnly?: boolean;
+    /** 只返回包含 lastReceivedLeafIndex 的消息（发送方有确认收到消息） */
+    hasLastReceivedIndexOnly?: boolean;
+    /** 按 lastReceivedLeafIndex 范围过滤 */
+    lastReceivedIndexMin?: number;
+    lastReceivedIndexMax?: number;
+    /**
+     * 名单过滤模式
+     * - "friends": 只返回好友列表中的发送者消息
+     * - "guard": 只返回 Guard 消息发送者消息
+     * - "stranger": 只返回陌生人消息（不在好友、Guard 列表中）
+     * - "any": 不过滤（默认）
+     */
+    listFilterMode?: "friends" | "guard" | "stranger" | "any";
+    /**
+     * 自定义名单过滤（高级用法）
+     * 与 listFilterMode 组合使用，实现交叉过滤
+     */
+    customListFilter?: {
+        /** 包含这些地址的消息（优先级最高） */
+        includeAddresses?: string[];
+        /** 排除这些地址的消息 */
+        excludeAddresses?: string[];
+        /** 地址列表关系："union" = 并集，"intersection" = 交集 */
+        relation?: "union" | "intersection";
+    };
+}
+export declare class MessengerError extends Error {
+    code: MessengerErrorCode;
+    cause?: Error | undefined;
+    constructor(code: MessengerErrorCode, message: string, cause?: Error | undefined);
+}
+/** Guard 列表项 */
+export interface GuardListItem {
+    guardAddress: string;
+    passportValiditySeconds: number;
+}
+/** 用户名单数据 */
+export interface ContactLists {
+    /** 好友列表 */
+    friends: string[];
+    /** Guard 列表 */
+    guards: GuardListItem[];
+    /** 最后更新时间 */
+    lastUpdatedAt: number;
+}
+/** 名单同步结果 */
+export interface ContactListsSyncResult {
+    success: boolean;
+    friends: string[];
+    guards: GuardListItem[];
+    error?: string;
+}
+/** 消息列表查询结果 */
+export interface MessageListResult {
+    /** 消息列表 */
+    messages: Message[];
+    /** 总数 */
+    total: number;
+    /** 当前页 */
+    offset: number;
+    /** 每页数量 */
+    limit: number;
+}
+/** 会话信息 */
+export interface ConversationInfo {
+    /** 对方地址 */
+    peerAddress: string;
+    /** 最后消息时间 */
+    lastMessageAt: number;
+    /** 消息总数 */
+    messageCount: number;
+    /** 未读消息数 */
+    unreadCount: number;
+    /** 最后一条消息预览 */
+    lastMessagePreview?: string;
+}
+/** 范围类型 */
+export type RangeType = "time" | "messageId" | "seqIndex";
+/** 基础范围 */
+export interface BaseRange {
+    /** 范围类型 */
+    type: RangeType;
+    /** 起始值 */
+    start: number | string;
+    /** 结束值 */
+    end: number | string;
+}
+/** 客户端时间范围 */
+export interface TimeRange extends BaseRange {
+    type: "time";
+    start: number;
+    end: number;
+}
+/** 消息ID范围 */
+export interface MessageIdRange extends BaseRange {
+    type: "messageId";
+    start: string;
+    end: string;
+}
+/** 序列索引范围（基于 leafIndex） */
+export interface SeqIndexRange extends BaseRange {
+    type: "seqIndex";
+    start: number;
+    end: number;
+}
+/** WTS 范围过滤参数 */
+export type WtsRange = TimeRange | MessageIdRange | SeqIndexRange;
+/** WTS 生成参数 */
+export interface WtsGenerationParams {
+    /** 我的账号 */
+    myAccount: string;
+    /** 对方账号 */
+    peerAccount: string;
+    /**
+     * 范围过滤参数
+     * 支持按客户端时间、服务器时间或消息索引（leafIndex）过滤
+     * 三种类型只需指定一种
+     */
+    range?: WtsRange;
+    /** 是否不包含明文（默认包含，设置为 true 时排除） */
+    excludePlaintext?: boolean;
+    /** 输出目录路径 */
+    outputDir: string;
+}
+/** WTS 文件结果 */
+export interface WtsFileResult {
+    /** 生成的 WTS 文件路径列表 */
+    files: string[];
+    /** 总消息数量 */
+    totalMessageCount: number;
+    /** 时间范围 */
+    timeRange: {
+        start: number;
+        end: number;
+    };
+}
+/** WTS 会话信息 */
+export interface WtsSession {
+    id: string;
+    participants: string[];
+}
+/** WTS 消息 */
+export interface WtsMessage {
+    id: string;
+    from: string;
+    to: string;
+    plaintext?: string;
+    plaintextHash: string;
+    clientTimestamp: number;
+    timestamp: number;
+    leafIndex: number;
+    prevRoot: string;
+    merkleRoot: string;
+    serverSignature: string;
+    serverPublicKey: string;
+    guardAddress?: string;
+    passportAddress?: string;
+    /** 最后收到的消息序号（用于消息同步确认） */
+    lastReceivedLeafIndex?: number;
+    arkConfirmed?: {
+        recipient: string;
+        recipientPublicKey: string;
+        signature: string;
+        timestamp: number;
+    };
+    msgType?: MessageType;
+    zipMetadata?: ZipMetadata;
+}
+/** WTS 载荷 */
+export interface WtsPayload {
+    session: WtsSession;
+    messages: WtsMessage[];
+}
+/** WTS 签名 */
+export interface WtsSignature {
+    value: string;
+    publicKey: string;
+    algorithm: "Ed25519";
+    address?: string;
+}
+/** WTS 服务器公钥 */
+export interface WtsServerPublicKey {
+    publicKey: string;
+    keyId?: string;
+    validFrom: number;
+    validUntil?: number;
+    algorithm?: string;
+}
+/** WTS 元数据 */
+export interface WtsMeta {
+    type: "wts";
+    version: string;
+    created: string;
+    hash: string;
+    algorithm: "sha256";
+    startTime: number;
+    endTime: number;
+    messageCount: number;
+    merkleRoot: string;
+    serverPublicKeys?: WtsServerPublicKey[];
+    signature?: WtsSignature | WtsSignature[];
+}
+/** WTS 文件结构 */
+export interface WtsFile {
+    wts: string;
+    payload: WtsPayload;
+    meta: WtsMeta;
+}
+/** WTS 签名验证详情 */
+export interface WtsSignatureVerification {
+    publicKey: string;
+    address?: string;
+    valid: boolean;
+}
+/** WTS 验证结果 */
+export interface WtsVerificationResult {
+    valid: boolean;
+    error?: string;
+    hashValid?: boolean;
+    hasSignature?: boolean;
+    signatureValid?: boolean;
+    signatures?: WtsSignatureVerification[];
+}
+/** WTS 转 HTML 选项 */
+export interface WtsToHtmlOptions {
+    title?: string;
+    theme?: "light" | "dark";
+    outputPath?: string;
+}
+export interface AddListRequest {
+    addresses: string[];
+}
+export interface AddGuardListRequest {
+    guards: GuardListItem[];
+}
+export interface RemoveListRequest {
+    addresses: string[];
+}
+export interface ClearListRequest {
+}
+export interface ExistListRequest {
+    addresses: string[];
+}
+export interface AddressExistence {
+    address: string;
+    exists: boolean;
+}
+export interface ListOperationResponse {
+    success: boolean;
+    operation: string;
+    modifiedCount: number;
+    currentCount: number;
+    maxCount: number;
+    invalidAddresses?: string[];
+    existResults?: AddressExistence[];
+    message?: string;
+    currentList?: string[];
+    currentGuardList?: GuardListItem[];
+}