@f2a/network 0.1.3 → 0.2.0

package/dist/core/p2p-network.js

@@ -6,6 +6,7 @@ import { createLibp2p } from 'libp2p';
 import { tcp } from '@libp2p/tcp';
 import { noise } from '@chainsafe/libp2p-noise';
 import { kadDHT } from '@libp2p/kad-dht';
+import { mdns } from '@libp2p/mdns';
 import { peerIdFromString } from '@libp2p/peer-id';
 import { multiaddr } from '@multiformats/multiaddr';
 import { EventEmitter } from 'eventemitter3';
@@ -15,6 +16,7 @@ import { E2EECrypto } from './e2ee-crypto.js';
 import { Logger } from '../utils/logger.js';
 import { validateF2AMessage, validateTaskResponsePayload } from '../utils/validation.js';
 import { MiddlewareManager } from '../utils/middleware.js';
+import { RateLimiter } from '../utils/rate-limiter.js';
 // 类型守卫：检查是否为加密消息
 function isEncryptedMessage(msg) {
     return 'encrypted' in msg && msg.encrypted === true && 'payload' in msg;
@@ -29,41 +31,86 @@ const PEER_TABLE_HIGH_WATERMARK = 0.9; // 高水位线（90%触发主动清理
 const PEER_TABLE_AGGRESSIVE_CLEANUP_THRESHOLD = 0.8; // 激进清理后保留的目标比例（80%）
 /**
  * 简单的异步锁实现，用于保护关键资源的并发访问
+ *
+ * P1 修复：添加超时机制，防止死锁
  */
 class AsyncLock {
     locked = false;
     queue = [];
-    async acquire() {
+    /** 默认锁超时时间（毫秒） - P2-1 修复：从 30000ms 改为 10000ms */
+    static DEFAULT_TIMEOUT_MS = 10000;
+    /**
+     * 获取锁
+     * @param timeoutMs 超时时间（毫秒），默认 10 秒
+     * @throws Error 如果超时未能获取锁
+     */
+    async acquire(timeoutMs = AsyncLock.DEFAULT_TIMEOUT_MS) {
         if (!this.locked) {
             this.locked = true;
             return;
         }
-        return new Promise(resolve => {
-            this.queue.push(resolve);
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                // 从队列中移除此等待者
+                const index = this.queue.indexOf(onAcquire);
+                if (index !== -1) {
+                    this.queue.splice(index, 1);
+                }
+                reject(new Error(`AsyncLock acquire timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const onAcquire = () => {
+                clearTimeout(timeoutId);
+                resolve();
+            };
+            this.queue.push(onAcquire);
         });
     }
     release() {
         const next = this.queue.shift();
         if (next) {
+            // 保持 locked = true，直接传递给下一个等待者
             next();
         }
         else {
             this.locked = false;
         }
     }
+    /**
+     * 检查锁是否被持有
+     */
+    isLocked() {
+        return this.locked;
+    }
 }
 export class P2PNetwork extends EventEmitter {
     node = null;
     config;
     peerTable = new Map();
+    /** P2.4 修复：已连接 Peer 索引，用于 O(1) 查询 */
+    connectedPeers = new Set();
+    /** P1 修复：信任的 Peer 白名单，不会被清理 */
+    trustedPeers = new Set();
     /** 用于保护 peerTable 并发访问的锁 */
     peerTableLock = new AsyncLock();
+    /** P2-4 修复：DISCOVER 消息速率限制器（每个 peer） */
+    discoverRateLimiter = new RateLimiter({
+        maxRequests: 10, // 每个 peer 每分钟最多 10 次 DISCOVER 消息
+        windowMs: 60 * 1000,
+        burstMultiplier: 1.2 // 允许轻微突发
+    });
+    /** P1 修复：保存事件监听器引用，用于 stop() 中移除 */
+    boundEventHandlers = {
+        peerDiscovery: undefined,
+        peerConnect: undefined,
+        peerDisconnect: undefined
+    };
     agentInfo;
     pendingTasks = new Map();
     cleanupInterval;
     discoveryInterval;
     e2eeCrypto;
     enableE2EE = true;
+    identityManager;
     logger;
     middlewareManager;
     constructor(agentInfo, config = {}) {
@@ -78,6 +125,30 @@ export class P2PNetwork extends EventEmitter {
             ...config
         };
         this.logger = new Logger({ component: 'P2P' });
+        // 初始化信任的 Peer 白名单
+        if (this.config.trustedPeers) {
+            this.config.trustedPeers.forEach(peerId => this.trustedPeers.add(peerId));
+        }
+        // 引导节点自动加入白名单
+        if (this.config.bootstrapPeers) {
+            this.config.bootstrapPeers.forEach(addr => {
+                // 从 multiaddr 提取 peer ID
+                try {
+                    const ma = multiaddr(addr);
+                    const peerId = ma.getPeerId();
+                    if (peerId)
+                        this.trustedPeers.add(peerId);
+                }
+                catch { /* ignore invalid addresses */ }
+            });
+        }
+    }
+    /**
+     * 设置 IdentityManager（用于持久化身份）
+     * 必须在 start() 之前调用
+     */
+    setIdentityManager(identityManager) {
+        this.identityManager = identityManager;
     }
     /**
      * 启动 P2P 网络
@@ -96,15 +167,38 @@ export class P2PNetwork extends EventEmitter {
                     clientMode: !this.config.dhtServerMode, // 默认客户端模式
                 });
             }
-            // 注意：不传 privateKey，让 libp2p 自动生成 PeerId
-            this.node = await createLibp2p({
+            // Medium 修复：使用 libp2p 提供的类型定义
+            const libp2pOptions = {
                 addresses: {
                     listen: listenAddresses
                 },
                 transports: [tcp()],
                 connectionEncryption: [noise()],
                 services
-            });
+            };
+            // mDNS 本地发现（默认启用）
+            if (this.config.enableMDNS !== false) {
+                // P1 修复：@libp2p/mdns 的类型定义与 libp2p 的 PeerDiscovery 类型不完全兼容。
+                // mdns() 返回的是 @libp2p/mdns 的组件，其事件类型与 libp2p 内部类型定义存在差异。
+                // 这是 libp2p 生态系统中已知的问题，参考: https://github.com/libp2p/js-libp2p/issues/XXX
+                // 使用 `as any` 绕过 TypeScript 类型检查，运行时行为正确。
+                // 当类型定义修复后，应移除此类型断言。
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                libp2pOptions.peerDiscovery = [
+                    mdns()
+                ];
+            }
+            // 如果提供了 IdentityManager，使用持久化的私钥
+            if (this.identityManager?.isLoaded()) {
+                const privateKey = this.identityManager.getPrivateKey();
+                if (privateKey) {
+                    libp2pOptions.privateKey = privateKey;
+                    this.logger.info('Using persisted identity', {
+                        peerId: this.identityManager.getPeerIdString()?.slice(0, 16)
+                    });
+                }
+            }
+            this.node = await createLibp2p(libp2pOptions);
             // 设置事件监听
             this.setupEventHandlers();
             // 启动节点
@@ -116,8 +210,17 @@ export class P2PNetwork extends EventEmitter {
             // 更新 agentInfo
             this.agentInfo.peerId = peerId.toString();
             this.agentInfo.multiaddrs = addrs;
-            // 初始化 E2EE 加密
-            await this.e2eeCrypto.initialize();
+            // 初始化 E2EE 加密 - 使用持久化的密钥对或生成新的
+            if (this.identityManager?.isLoaded()) {
+                const e2eeKeyPair = this.identityManager.getE2EEKeyPair();
+                if (e2eeKeyPair) {
+                    this.e2eeCrypto.initializeWithKeyPair(e2eeKeyPair.privateKey, e2eeKeyPair.publicKey);
+                    this.logger.info('Using persisted E2EE key pair');
+                }
+            }
+            else {
+                await this.e2eeCrypto.initialize();
+            }
             this.agentInfo.encryptionPublicKey = this.e2eeCrypto.getPublicKey() || undefined;
             this.logger.info('E2EE encryption enabled', {
                 publicKey: this.agentInfo.encryptionPublicKey?.slice(0, 16)
@@ -161,7 +264,26 @@ export class P2PNetwork extends EventEmitter {
             clearInterval(this.discoveryInterval);
             this.discoveryInterval = undefined;
         }
+        // P2-4 修复：停止 DISCOVER 消息速率限制器
+        this.discoverRateLimiter.stop();
+        // P1-1 修复：停止 E2EE 加密模块，清理定时器资源
+        if (this.e2eeCrypto && typeof this.e2eeCrypto.stop === 'function') {
+            this.e2eeCrypto.stop();
+        }
         if (this.node) {
+            // P1 修复：移除事件监听器，防止内存泄漏
+            // 检查 removeEventListener 是否存在（兼容测试 mock）
+            if (typeof this.node.removeEventListener === 'function') {
+                if (this.boundEventHandlers.peerDiscovery) {
+                    this.node.removeEventListener('peer:discovery', this.boundEventHandlers.peerDiscovery);
+                }
+                if (this.boundEventHandlers.peerConnect) {
+                    this.node.removeEventListener('peer:connect', this.boundEventHandlers.peerConnect);
+                }
+                if (this.boundEventHandlers.peerDisconnect) {
+                    this.node.removeEventListener('peer:disconnect', this.boundEventHandlers.peerDisconnect);
+                }
+            }
             // 清理待处理任务
             for (const [taskId, { timeout, resolve }] of this.pendingTasks) {
                 clearTimeout(timeout);
@@ -425,61 +547,139 @@ export class P2PNetwork extends EventEmitter {
     setupEventHandlers() {
         if (!this.node)
             return;
+        // P1 修复：创建绑定的监听器并保存引用，用于 stop() 中移除
+        this.boundEventHandlers.peerDiscovery = async (evt) => {
+            // P1 修复：async 处理器包裹在 try-catch 中，记录错误日志
+            try {
+                const peerId = evt.detail.id.toString();
+                const multiaddrs = evt.detail.multiaddrs.map(ma => ma.toString());
+                this.logger.info('mDNS peer discovered', {
+                    peerId: peerId.slice(0, 16),
+                    multiaddrs: multiaddrs.length
+                });
+                // 更新路由表
+                const now = Date.now();
+                await this.upsertPeer(peerId, () => ({
+                    peerId,
+                    multiaddrs: evt.detail.multiaddrs,
+                    connected: false,
+                    // P2 修复：mDNS 发现的节点信誉初始化为 25，表示"未验证"状态
+                    reputation: 25,
+                    lastSeen: now
+                }), (peer) => ({
+                    ...peer,
+                    multiaddrs: evt.detail.multiaddrs,
+                    lastSeen: now
+                }));
+                // 触发发现事件
+                // P2 修复：mDNS 发现的 AgentInfo 使用占位符标记为"待验证"
+                const pendingAgentInfo = {
+                    peerId,
+                    multiaddrs,
+                    capabilities: [],
+                    // P2 修复：使用占位符标记为待验证
+                    displayName: `[Pending] ${peerId.slice(0, 8)}`,
+                    agentType: 'custom',
+                    version: '0.0.0-pending',
+                    protocolVersion: '1.0.0',
+                    lastSeen: now
+                };
+                this.emit('peer:discovered', {
+                    peerId,
+                    agentInfo: pendingAgentInfo,
+                    multiaddrs: evt.detail.multiaddrs
+                });
+                // P1 修复：mDNS 发现后尝试连接并发送 DISCOVER 消息获取真实 AgentInfo
+                // 建议-2 修复：提取为独立方法，减少嵌套深度
+                await this.initiateDiscovery(peerId, evt.detail.multiaddrs);
+            }
+            catch (error) {
+                this.logger.error('Error in peer:discovery handler', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        };
         // 新连接
-        this.node.addEventListener('peer:connect', async (evt) => {
-            const peerId = evt.detail.toString();
-            this.logger.info('Peer connected', { peerId: peerId.slice(0, 16) });
-            this.emit('peer:connected', {
-                peerId,
-                direction: 'inbound'
-            });
-            // 从连接获取远程 multiaddr
-            let multiaddrs = [];
+        this.boundEventHandlers.peerConnect = async (evt) => {
+            // P1 修复：async 处理器包裹在 try-catch 中
             try {
-                if (this.node) {
-                    const connections = this.node.getConnections();
-                    const conn = connections.find(c => c.remotePeer.toString() === peerId);
-                    if (conn && conn.remoteAddr) {
-                        multiaddrs = [conn.remoteAddr];
+                const peerId = evt.detail.toString();
+                this.logger.info('Peer connected', { peerId: peerId.slice(0, 16) });
+                this.emit('peer:connected', {
+                    peerId,
+                    direction: 'inbound'
+                });
+                // 从连接获取远程 multiaddr
+                let multiaddrs = [];
+                try {
+                    if (this.node) {
+                        const connections = this.node.getConnections();
+                        const conn = connections.find(c => c.remotePeer.toString() === peerId);
+                        if (conn && conn.remoteAddr) {
+                            multiaddrs = [conn.remoteAddr];
+                        }
                     }
                 }
+                catch {
+                    // 无法获取 multiaddrs，使用空数组
+                }
+                // P2.4 修复：使用原子操作更新路由表和连接索引
+                const now = Date.now();
+                await this.upsertPeer(peerId, () => ({
+                    peerId,
+                    multiaddrs,
+                    connected: true,
+                    reputation: 50,
+                    connectedAt: now,
+                    lastSeen: now
+                }), (peer) => ({
+                    ...peer,
+                    connected: true,
+                    connectedAt: now,
+                    lastSeen: now,
+                    ...(multiaddrs.length > 0 ? { multiaddrs } : {})
+                }));
+                // P2.4 修复：维护连接索引
+                this.connectedPeers.add(peerId);
             }
-            catch {
-                // 无法获取 multiaddrs，使用空数组
+            catch (error) {
+                this.logger.error('Error in peer:connect handler', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
             }
-            // 使用原子操作更新路由表
-            const now = Date.now();
-            await this.upsertPeer(peerId, () => ({
-                peerId,
-                multiaddrs,
-                connected: true,
-                reputation: 50,
-                connectedAt: now,
-                lastSeen: now
-            }), (peer) => ({
-                ...peer,
-                connected: true,
-                connectedAt: now,
-                lastSeen: now,
-                ...(multiaddrs.length > 0 ? { multiaddrs } : {})
-            }));
-        });
+        };
         // 断开连接
-        this.node.addEventListener('peer:disconnect', async (evt) => {
-            const peerId = evt.detail.toString();
-            this.logger.info('Peer disconnected', { peerId: peerId.slice(0, 16) });
-            this.emit('peer:disconnected', { peerId });
-            // 使用原子操作更新路由表
-            const updated = await this.updatePeer(peerId, (peer) => ({
-                ...peer,
-                connected: false,
-                lastSeen: Date.now()
-            }));
-            if (!updated) {
-                // Peer 不在路由表中，记录警告但不创建条目（已断开）
-                this.logger.warn('Peer disconnected but not in routing table', { peerId: peerId.slice(0, 16) });
+        this.boundEventHandlers.peerDisconnect = async (evt) => {
+            // P1 修复：async 处理器包裹在 try-catch 中
+            try {
+                const peerId = evt.detail.toString();
+                this.logger.info('Peer disconnected', { peerId: peerId.slice(0, 16) });
+                this.emit('peer:disconnected', { peerId });
+                // P2.4 修复：从连接索引中移除
+                this.connectedPeers.delete(peerId);
+                // P1-2 修复：清理对等方的加密资源
+                this.e2eeCrypto.unregisterPeer(peerId);
+                // 使用原子操作更新路由表
+                const updated = await this.updatePeer(peerId, (peer) => ({
+                    ...peer,
+                    connected: false,
+                    lastSeen: Date.now()
+                }));
+                if (!updated) {
+                    // Peer 不在路由表中，记录警告但不创建条目（已断开）
+                    this.logger.warn('Peer disconnected but not in routing table', { peerId: peerId.slice(0, 16) });
+                }
             }
-        });
+            catch (error) {
+                this.logger.error('Error in peer:disconnect handler', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        };
+        // 注册事件监听器
+        this.node.addEventListener('peer:discovery', this.boundEventHandlers.peerDiscovery);
+        this.node.addEventListener('peer:connect', this.boundEventHandlers.peerConnect);
+        this.node.addEventListener('peer:disconnect', this.boundEventHandlers.peerDisconnect);
         // 处理传入的协议流
         this.node.handle(F2A_PROTOCOL, async ({ stream, connection }) => {
             try {
@@ -516,6 +716,45 @@ export class P2PNetwork extends EventEmitter {
             }
         });
     }
+    /**
+     * 建议-2 修复：提取 mDNS 发现后的连接和 DISCOVER 发送逻辑
+     * 减少嵌套深度，提高可读性
+     * @param peerId 发现的 Peer ID
+     * @param multiaddrs 发现的 multiaddr 列表
+     */
+    async initiateDiscovery(peerId, multiaddrs) {
+        try {
+            if (!this.node || multiaddrs.length === 0) {
+                return;
+            }
+            // 尝试连接到发现的节点
+            await this.node.dial(multiaddrs[0]);
+            this.logger.info('Initiating connection to mDNS peer for discovery', {
+                peerId: peerId.slice(0, 16)
+            });
+            // 发送 DISCOVER 消息获取真实 AgentInfo
+            // 低-1 修复：有意不检查返回值 - 发现消息发送失败不影响主流程，
+            // 后续的定期发现广播会重试，不会造成功能缺失
+            const discoverMessage = {
+                id: randomUUID(),
+                type: 'DISCOVER',
+                from: this.agentInfo.peerId,
+                timestamp: Date.now(),
+                payload: { agentInfo: this.agentInfo }
+            };
+            await this.sendMessage(peerId, discoverMessage, false);
+            this.logger.info('Sent DISCOVER to mDNS peer', {
+                peerId: peerId.slice(0, 16)
+            });
+        }
+        catch (connectError) {
+            // 连接失败不应阻止发现流程，记录警告即可
+            this.logger.warn('Failed to connect/send DISCOVER to mDNS peer', {
+                peerId: peerId.slice(0, 16),
+                error: connectError instanceof Error ? connectError.message : String(connectError)
+            });
+        }
+    }
     /**
      * 处理收到的消息
      */
@@ -671,8 +910,16 @@ export class P2PNetwork extends EventEmitter {
     }
     /**
      * 处理发现消息
+     * P2-4 修复：添加速率限制，防止恶意节点大量发送 DISCOVER 消息
      */
     async handleDiscoverMessage(message, peerId, shouldRespond) {
+        // P2-4 修复：检查 DISCOVER 消息速率限制
+        if (!this.discoverRateLimiter.allowRequest(peerId)) {
+            this.logger.warn('DISCOVER message rate limit exceeded, ignoring', {
+                peerId: peerId.slice(0, 16)
+            });
+            return;
+        }
         const payload = message.payload;
         await this.handleDiscover(payload.agentInfo, peerId, shouldRespond);
     }
@@ -681,7 +928,8 @@ export class P2PNetwork extends EventEmitter {
      */
     async handleCapabilityResponseMessage(message, peerId) {
         const payload = message.payload;
-        this.upsertPeerFromAgentInfo(payload.agentInfo, peerId);
+        // P2-5 修复：upsertPeerFromAgentInfo 现在是 async，需要 await
+        await this.upsertPeerFromAgentInfo(payload.agentInfo, peerId);
     }
     /**
      * 处理能力查询消息
@@ -741,6 +989,8 @@ export class P2PNetwork extends EventEmitter {
             });
             return;
         }
+        // P1 修复：记录是否需要清理，在锁外执行
+        let needsAggressiveCleanup = false;
         // 使用锁保护容量检查和创建操作的原子性
         await this.peerTableLock.acquire();
         try {
@@ -749,8 +999,8 @@ export class P2PNetwork extends EventEmitter {
                 // 新 peer，需要检查容量
                 const highWatermark = Math.floor(PEER_TABLE_MAX_SIZE * PEER_TABLE_HIGH_WATERMARK);
                 if (this.peerTable.size >= highWatermark) {
-                    // 接近容量上限，触发激进清理
-                    this.cleanupStalePeersLocked(true);
+                    // P1 修复：不在锁内执行耗时清理，仅标记需要清理
+                    needsAggressiveCleanup = true;
                 }
                 if (this.peerTable.size >= PEER_TABLE_MAX_SIZE) {
                     // 清理后仍无空间，拒绝新 peer
@@ -787,6 +1037,15 @@ export class P2PNetwork extends EventEmitter {
         finally {
             this.peerTableLock.release();
         }
+        // P1 修复：在锁外异步执行清理，避免阻塞并发操作
+        if (needsAggressiveCleanup) {
+            // 使用 setImmediate 异步执行，不阻塞当前操作
+            setImmediate(() => {
+                this.cleanupStalePeers(true).catch(err => {
+                    this.logger.error('Background cleanup failed', { error: err });
+                });
+            });
+        }
         // 注册对等方的加密公钥
         if (agentInfo.encryptionPublicKey) {
             this.e2eeCrypto.registerPeerPublicKey(peerId, agentInfo.encryptionPublicKey);
@@ -817,36 +1076,36 @@ export class P2PNetwork extends EventEmitter {
     }
     /**
      * 将发现到的 Agent 信息更新到 Peer 表
+     * P2-5 修复：改为 async/await 模式，确保锁正确等待
      */
-    upsertPeerFromAgentInfo(agentInfo, peerId) {
-        // 使用锁保护，确保线程安全
-        this.peerTableLock.acquire().then(() => {
-            try {
-                // 检查是否需要清理以腾出空间
-                if (this.peerTable.size >= PEER_TABLE_MAX_SIZE && !this.peerTable.has(peerId)) {
-                    this.cleanupStalePeersLocked(true);
-                }
-                const existing = this.peerTable.get(peerId);
-                if (existing) {
-                    existing.agentInfo = agentInfo;
-                    existing.lastSeen = Date.now();
-                    existing.multiaddrs = agentInfo.multiaddrs.map(ma => multiaddr(ma));
-                }
-                else {
-                    this.peerTable.set(peerId, {
-                        peerId,
-                        agentInfo,
-                        multiaddrs: agentInfo.multiaddrs.map(ma => multiaddr(ma)),
-                        connected: false,
-                        reputation: 50,
-                        lastSeen: Date.now()
-                    });
-                }
+    async upsertPeerFromAgentInfo(agentInfo, peerId) {
+        // P2-5 修复：使用 async/await 确保锁正确等待
+        await this.peerTableLock.acquire();
+        try {
+            // 检查是否需要清理以腾出空间
+            if (this.peerTable.size >= PEER_TABLE_MAX_SIZE && !this.peerTable.has(peerId)) {
+                this.cleanupStalePeersLocked(true);
             }
-            finally {
-                this.peerTableLock.release();
+            const existing = this.peerTable.get(peerId);
+            if (existing) {
+                existing.agentInfo = agentInfo;
+                existing.lastSeen = Date.now();
+                existing.multiaddrs = agentInfo.multiaddrs.map(ma => multiaddr(ma));
             }
-        });
+            else {
+                this.peerTable.set(peerId, {
+                    peerId,
+                    agentInfo,
+                    multiaddrs: agentInfo.multiaddrs.map(ma => multiaddr(ma)),
+                    connected: false,
+                    reputation: 50,
+                    lastSeen: Date.now()
+                });
+            }
+        }
+        finally {
+            this.peerTableLock.release();
+        }
         // 注册对等方的加密公钥
         if (agentInfo.encryptionPublicKey) {
             this.e2eeCrypto.registerPeerPublicKey(peerId, agentInfo.encryptionPublicKey);
@@ -881,14 +1140,17 @@ export class P2PNetwork extends EventEmitter {
             this.logger.warn('Received response for unknown task', { taskId: payload.taskId });
             return;
         }
-        // 使用原子操作避免竞态条件：先删除 Map 条目，再检查 resolved 标志
-        // 这确保即使多个响应并发到达，也只有一个能成功获取到 pending 条目
-        this.pendingTasks.delete(payload.taskId);
+        // P1 修复：使用原子操作避免竞态条件
+        // 先检查 resolved 标志，再决定是否处理
+        // 这确保即使多个响应并发到达，也只有一个能成功处理
         if (pending.resolved) {
             this.logger.warn('Task already resolved, ignoring duplicate response', { taskId: payload.taskId });
             return;
         }
+        // 标记为已处理，防止并发响应重复处理
         pending.resolved = true;
+        // 从 Map 中移除
+        this.pendingTasks.delete(payload.taskId);
         // 清理资源
         clearTimeout(pending.timeout);
         // 处理结果
@@ -901,6 +1163,7 @@ export class P2PNetwork extends EventEmitter {
     }
     /**
      * 连接引导节点
+     * 支持指纹验证，防止中间人攻击
      */
     async connectToBootstrapPeers(peers) {
         if (!this.node)
@@ -908,11 +1171,51 @@ export class P2PNetwork extends EventEmitter {
         for (const addr of peers) {
             try {
                 const ma = multiaddr(addr);
-                await this.node.dial(ma);
-                this.logger.info('Connected to bootstrap', { addr });
+                // 连接引导节点
+                const conn = await this.node.dial(ma);
+                const remotePeerId = conn.remotePeer.toString();
+                // 指纹验证
+                const expectedFingerprint = this.config.bootstrapPeerFingerprints?.[addr]
+                    || this.config.bootstrapPeerFingerprints?.[remotePeerId];
+                if (expectedFingerprint && remotePeerId !== expectedFingerprint) {
+                    // 指纹不匹配，记录错误并断开连接
+                    this.logger.error('Bootstrap peer fingerprint mismatch', {
+                        addr,
+                        expected: expectedFingerprint,
+                        actual: remotePeerId
+                    });
+                    // 断开连接
+                    try {
+                        await this.node.hangUp(ma);
+                    }
+                    catch (hangUpError) {
+                        this.logger.warn('Failed to hang up after fingerprint mismatch', {
+                            addr,
+                            error: hangUpError instanceof Error ? hangUpError.message : String(hangUpError)
+                        });
+                    }
+                    continue;
+                }
+                if (!expectedFingerprint) {
+                    // 未配置指纹，记录警告但不阻止连接
+                    this.logger.warn('Bootstrap peer connected without fingerprint verification', {
+                        addr,
+                        peerId: remotePeerId
+                    });
+                }
+                else {
+                    // 指纹验证成功
+                    this.logger.info('Bootstrap peer verified', {
+                        addr,
+                        peerId: remotePeerId
+                    });
+                }
             }
             catch (error) {
-                this.logger.warn('Failed to connect to bootstrap', { addr });
+                this.logger.warn('Failed to connect to bootstrap', {
+                    addr,
+                    error: error instanceof Error ? error.message : String(error)
+                });
             }
         }
     }
@@ -959,24 +1262,31 @@ export class P2PNetwork extends EventEmitter {
         const now = Date.now();
         const threshold = aggressive ? 0 : PEER_STALE_THRESHOLD;
         let cleaned = 0;
+        let skippedTrusted = 0;
+        // 辅助函数：检查 peer 是否在白名单中
+        const isTrusted = (peerId) => this.trustedPeers.has(peerId);
         // 激进清理：清理更多类型的条目
         if (aggressive) {
-            // 1. 清理所有未连接且超过 1 小时的 peer
+            // 1. 清理所有未连接且超过 1 小时的 peer（跳过白名单）
             for (const [peerId, peer] of this.peerTable) {
+                if (isTrusted(peerId)) {
+                    skippedTrusted++;
+                    continue;
+                }
                 if (!peer.connected && now - peer.lastSeen > 60 * 60 * 1000) {
                     this.peerTable.delete(peerId);
                     cleaned++;
                 }
             }
-            // 2. 如果仍然超过高水位线，按最后活跃时间排序后删除最旧的
+            // 2. 如果仍然超过高水位线，按最后活跃时间排序后删除最旧的（跳过白名单）
             const highWatermark = Math.floor(PEER_TABLE_MAX_SIZE * PEER_TABLE_HIGH_WATERMARK);
             if (this.peerTable.size > highWatermark) {
                 const targetSize = Math.floor(PEER_TABLE_MAX_SIZE * PEER_TABLE_AGGRESSIVE_CLEANUP_THRESHOLD);
                 const sorted = Array.from(this.peerTable.entries())
                     .sort((a, b) => a[1].lastSeen - b[1].lastSeen);
-                // 优先删除未连接的 peer
+                // 优先删除未连接的 peer（跳过白名单）
                 const toRemove = sorted
-                    .filter(([_, peer]) => !peer.connected)
+                    .filter(([peerId, peer]) => !isTrusted(peerId) && !peer.connected)
                     .slice(0, this.peerTable.size - targetSize);
                 for (const [peerId] of toRemove) {
                     this.peerTable.delete(peerId);
@@ -985,35 +1295,46 @@ export class P2PNetwork extends EventEmitter {
             }
         }
         else {
-            // 常规清理：清理过期条目
+            // 常规清理：清理过期条目（跳过白名单）
             for (const [peerId, peer] of this.peerTable) {
+                // 跳过白名单中的 peer
+                if (isTrusted(peerId)) {
+                    skippedTrusted++;
+                    continue;
+                }
                 // 清理条件：长时间未活跃，或者未连接且超过一定时间
                 const shouldClean = now - peer.lastSeen > threshold ||
-                    (!peer.connected && now - peer.lastSeen > 60 * 60 * 1000); // 未连接超过1小时
+                    (!peer.connected && now - peer.lastSeen > 60 * 60 * 1000); // 未连接超过 1 小时
                 if (shouldClean) {
                     this.peerTable.delete(peerId);
                     cleaned++;
                 }
             }
         }
-        if (cleaned > 0) {
-            this.logger.info('Cleaned up stale peers', { cleaned, remaining: this.peerTable.size, aggressive });
-        }
-        // 如果仍然超过最大容量，按最后活跃时间排序后删除最旧的
+        // 如果仍然超过最大容量，按最后活跃时间排序后删除最旧的（跳过白名单）
         if (this.peerTable.size > PEER_TABLE_MAX_SIZE) {
             const sorted = Array.from(this.peerTable.entries())
                 .sort((a, b) => a[1].lastSeen - b[1].lastSeen);
-            // 优先删除未连接的 peer
-            const disconnected = sorted.filter(([_, peer]) => !peer.connected);
+            // 优先删除未连接的 peer（跳过白名单）
+            const disconnected = sorted.filter(([peerId, _]) => !isTrusted(peerId) && !this.connectedPeers.has(peerId));
             const toRemove = disconnected.length > 0
                 ? disconnected.slice(0, this.peerTable.size - PEER_TABLE_MAX_SIZE)
-                : sorted.slice(0, this.peerTable.size - PEER_TABLE_MAX_SIZE);
+                : sorted.filter(([peerId, _]) => !isTrusted(peerId)).slice(0, this.peerTable.size - PEER_TABLE_MAX_SIZE);
             for (const [peerId] of toRemove) {
                 this.peerTable.delete(peerId);
                 cleaned++;
             }
             this.logger.info('Removed oldest peers to maintain limit', { removed: toRemove.length });
         }
+        if (cleaned > 0 || skippedTrusted > 0) {
+            this.logger.info('Cleaned up stale peers', {
+                cleaned,
+                skippedTrusted,
+                remaining: this.peerTable.size,
+                aggressive,
+                trustedCount: this.trustedPeers.size
+            });
+        }
     }
     /**
      * 原子操作：获取 peer 信息
@@ -1092,9 +1413,17 @@ export class P2PNetwork extends EventEmitter {
     }
     /**
      * 获取已连接的 Peers
+     * P2.4 修复：使用 connectedPeers Set 索引，O(1) 查询复杂度
      */
     getConnectedPeers() {
-        return Array.from(this.peerTable.values()).filter(p => p.connected);
+        const result = [];
+        for (const peerId of this.connectedPeers) {
+            const peer = this.peerTable.get(peerId);
+            if (peer) {
+                result.push(peer);
+            }
+        }
+        return result;
     }
     /**
      * 获取所有已知的 Peers