@lyrify/znl 0.5.1 → 0.5.6

package/README.md

@@ -13,7 +13,10 @@
 - 加密开关 `encrypted`：
   - `false`：明文模式（不签名/不加密）
   - `true`：签名 + 防重放 + payload 透明加密（AES-256-GCM）
-- `authKey` 仅在 `encrypted=true` 时必填
+- 可选关闭 payload 摘要校验（`enablePayloadDigest=false`）以提升性能
+  - 建议 master/slave 两端保持一致配置，避免认证不一致
+- `authKey` 或 `authKeyMap` 仅在 `encrypted=true` 时必填
+- `authKeyMap` 支持 master 按 `slaveId` 配置不同 key（未命中时会回退到 `authKey`）
 - Payload 支持 `string`、`Buffer`、`Uint8Array` 及其数组（多帧）
 
 ## 安装
@@ -99,9 +102,13 @@ new ZNL({
   endpoints: {
     router: "tcp://127.0.0.1:6003",
   },
-  maxPending: 0,
+  maxPending: 1000,
   authKey: "",
+  authKeyMap: { "slave-001": "k1", "slave-002": "k2" },
+  heartbeatInterval: 3000,
+  heartbeatTimeoutMs: 0,
   encrypted: false,
+  enablePayloadDigest: true,
   maxTimeSkewMs: 30000,
   replayWindowMs: 120000,
 });
@@ -112,9 +119,13 @@ new ZNL({
 | `role` | ✓ | 节点角色，`"master"` 或 `"slave"` |
 | `id` | ✓ | 节点唯一标识；slave 端同时作为 ZMQ `routingId` |
 | `endpoints.router` | | ROUTER 端点，默认 `tcp://127.0.0.1:6003` |
-| `maxPending` | | 最大并发 RPC 请求数，`0` 表示不限制 |
-| `authKey` | | 共享认证 Key；仅在 `encrypted=true` 时必填（用于签名/加密） |
+| `maxPending` | | 最大并发 RPC 请求数，默认 `1000`；`0` 表示不限制 |
+| `authKey` | | 共享认证 Key；与 `authKeyMap` 二选一（`encrypted=true` 时至少提供一个） |
+| `authKeyMap` | | master 侧 slaveId → authKey 映射；未命中时回退到 `authKey` |
+| `heartbeatInterval` | | 心跳间隔（毫秒），默认 `3000`，`0` 表示禁用心跳 |
+| `heartbeatTimeoutMs` | | 心跳超时时间（毫秒），默认 `0` 表示使用 `heartbeatInterval × 3` |
 | `encrypted` | | 是否启用加密：`false`（默认，明文） / `true`（签名+防重放+透明加密） |
+| `enablePayloadDigest` | | 是否启用 payload 摘要校验，默认 `true`（关闭可提升性能） |
 | `maxTimeSkewMs` | | 时间戳最大允许偏移（毫秒），默认 `30000`，用于防重放校验 |
 | `replayWindowMs` | | nonce 重放缓存窗口（毫秒），默认 `120000` |
 
@@ -150,6 +161,18 @@ new ZNL({
 - `identityOrHandler` 为函数时：注册 master 侧自动回复处理器（Slave 发来 RPC 请求时触发）
 - `identityOrHandler` 为 identity（slave ID）时：Master 主动向指定 Slave 发送 RPC 请求并等待响应，返回 `Promise<Buffer | Array>`
 
+### `addAuthKey(slaveId, authKey)`
+
+**Master 侧调用：**
+
+- 动态添加/更新某个 slave 的 authKey（立即生效）
+
+### `removeAuthKey(slaveId)`
+
+**Master 侧调用：**
+
+- 移除某个 slave 的 authKey（立即生效），并触发 `slave_disconnected`
+
 ### `options.timeoutMs`
 
 单次 RPC 请求超时时间，默认 `5000` ms。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyrify/znl",
-  "version": "0.5.1",
+  "version": "0.5.6",
   "description": "ZNL - ZeroMQ Node Link",
   "type": "module",
   "main": "./index.js",
@@ -35,12 +35,24 @@
   "dependencies": {
     "zeromq": "^6.5.0"
   },
+  "devDependencies": {
+    "eslint": "^9.39.4",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.8.1"
+  },
   "scripts": {
     "example:master": "node test/master/index.js",
     "example:slave": "node test/slave/index.js",
     "test": "node test/run.js",
+    "test:unit": "node --test \"test/unit/**/*.test.js\"",
+    "test:all": "pnpm test && pnpm test:unit",
     "test:echo": "node test/master/test-echo-server.js",
     "test:100": "node test/slave/test-100-concurrent.js",
-    "check": "node --check index.js && node --check src/constants.js && node --check src/protocol.js && node --check src/security.js && node --check src/PendingManager.js && node --check src/SendQueue.js && node --check src/ZNL.js && node --check test/master/index.js && node --check test/slave/index.js && node --check test/master/test-echo-server.js && node --check test/slave/test-100-concurrent.js && node --check test/run.js"
+    "test:capture": "node test/capture-frames.js",
+    "check": "node --check index.js && node --check src/constants.js && node --check src/protocol.js && node --check src/security.js && node --check src/PendingManager.js && node --check src/SendQueue.js && node --check src/ZNL.js && node --check test/master/index.js && node --check test/slave/index.js && node --check test/master/test-echo-server.js && node --check test/slave/test-100-concurrent.js && node --check test/run.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier . --check",
+    "format:write": "prettier . --write"
   }
 }

package/src/SendQueue.js

@@ -6,17 +6,15 @@
  * 虽然 zeromq.js v6 在 JS 层做了一定保护，但显式串行化更安全可靠。
  *
  * 实现原理：
- * 为每个 socket 通道维护一条 Promise 链（队列尾指针）。
- * 每次入队时，新任务追加在当前链尾，前一个任务完成后自动触发。
- * 无论前一个任务成功或失败，队列都会继续执行下一个任务。
+ * 为每个 socket 通道维护一个任务队列与独立消费循环。
+ * 通过单线程 async loop 串行执行，避免长 Promise 链增长。
  */
-
 export class SendQueue {
   /**
-   * 各通道的队列尾指针
-   * @type {Map<string, Promise<void>>}
+   * 通道级队列与运行状态
+   * @type {Map<string, { queue: Array<{ task: Function, resolve: Function, reject: Function }>, running: boolean }>}
    */
-  #tails = new Map();
+  #channels = new Map();
 
   /**
    * 将发送任务追加到指定通道的队列尾部
@@ -26,22 +24,58 @@ export class SendQueue {
    * @returns {Promise<void>} 本次任务的 Promise（可用于错误捕获）
    */
   enqueue(channel, task) {
-    const tail = this.#tails.get(channel) ?? Promise.resolve();
-
-    // 无论前一个任务成功或失败，都继续执行当前任务
-    const run = tail.then(task, task);
+    const name = String(channel);
+    const entry = this.#ensureChannel(name);
 
-    // 更新队尾（吞掉错误，防止产生 UnhandledRejection）
-    this.#tails.set(channel, run.catch(() => {}));
-
-    return run;
+    return new Promise((resolve, reject) => {
+      entry.queue.push({ task, resolve, reject });
+      if (!entry.running) this.#drain(name, entry);
+    });
   }
 
   /**
    * 清空所有通道的队列引用（节点停止时调用）
-   * 注意：已入队但未执行的任务不会被取消，仅释放尾指针引用
+   * 注意：已入队但未执行的任务不会被取消，仅释放引用
    */
   clear() {
-    this.#tails.clear();
+    this.#channels.clear();
+  }
+
+  /**
+   * 确保通道数据结构存在
+   * @param {string} name
+   * @returns {{ queue: Array, running: boolean }}
+   */
+  #ensureChannel(name) {
+    let entry = this.#channels.get(name);
+    if (!entry) {
+      entry = { queue: [], running: false };
+      this.#channels.set(name, entry);
+    }
+    return entry;
+  }
+
+  /**
+   * 串行消费队列
+   * @param {string} name
+   * @param {{ queue: Array, running: boolean }} entry
+   */
+  async #drain(name, entry) {
+    entry.running = true;
+
+    while (entry.queue.length > 0) {
+      const { task, resolve, reject } = entry.queue.shift();
+      try {
+        await task();
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    }
+
+    entry.running = false;
+
+    // 清理空通道，避免 Map 无限增长
+    if (entry.queue.length === 0) this.#channels.delete(name);
   }
 }

package/src/ZNL.js

@@ -20,7 +20,8 @@
  * 心跳机制：
  *  - slave 每隔 heartbeatInterval ms 向 master 发送一帧心跳
  *  - master 每隔 heartbeatInterval ms 扫描一次在线列表
- *  - 超过 heartbeatInterval × 3 ms 未收到心跳，判定 slave 已崩溃并移除
+ *  - 超过 heartbeatTimeoutMs 未收到心跳，判定 slave 已崩溃并移除
+ *    （heartbeatTimeoutMs <= 0 时，默认按 heartbeatInterval × 3 计算）
  */
 
 import { randomUUID } from "node:crypto";
@@ -30,6 +31,9 @@ import * as zmq from "zeromq";
 import {
   DEFAULT_ENDPOINTS,
   DEFAULT_HEARTBEAT_INTERVAL,
+  DEFAULT_HEARTBEAT_TIMEOUT_MS,
+  DEFAULT_MAX_PENDING,
+  DEFAULT_ENABLE_PAYLOAD_DIGEST,
   CONTROL_PREFIX,
   CONTROL_HEARTBEAT,
   SECURITY_ENVELOPE_VERSION,
@@ -59,7 +63,6 @@ import {
   generateNonce,
   nowMs,
   canonicalSignInput,
-  signText,
   encodeAuthProofToken,
   decodeAuthProofToken,
   encryptFrames,
@@ -118,13 +121,25 @@ export class ZNL extends EventEmitter {
   /** @type {Function|null} slave 侧收到 master 请求时的自动回复处理器 */
   #dealerAutoHandler = null;
 
+  /** @type {number} 心跳超时时间（ms），0 表示使用 interval × 3 */
+  #heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS;
+
+  /** @type {boolean} 是否启用 payload 摘要校验（安全模式用） */
+  #enablePayloadDigest = DEFAULT_ENABLE_PAYLOAD_DIGEST;
+
+  /** @type {Map<string, string>} master 侧 authKey 配置表（按 slaveId） */
+  #authKeyMap = new Map();
+
+  /** @type {Map<string, { signKey: Buffer, encryptKey: Buffer }>} master 侧派生密钥缓存 */
+  #slaveKeyCache = new Map();
+
   // ─── PUB/SUB 状态 ────────────────────────────────────────────────────────
 
   /**
    * master 侧：已注册的在线 slave 表
    * key   = slaveId（字符串）
-   * value = { identity: Buffer, lastSeen: number }
-   * @type {Map<string, { identity: Buffer, lastSeen: number }>}
+   * value = { identity: Buffer, lastSeen: number, signKey: Buffer|null, encryptKey: Buffer|null }
+   * @type {Map<string, { identity: Buffer, lastSeen: number, signKey: Buffer|null, encryptKey: Buffer|null }>}
    */
   #slaves = new Map();
 
@@ -174,22 +189,28 @@ export class ZNL extends EventEmitter {
    *   role               : "master"|"slave",
    *   id                 : string,
    *   endpoints?         : { router?: string },
-   *   maxPending?        : number,
-   *   authKey?           : string,
-   *   heartbeatInterval? : number,
-   *   encrypted?         : boolean,
-   *   maxTimeSkewMs?     : number,
-   *   replayWindowMs?    : number,
+   *   maxPending?          : number,
+   *   authKey?             : string,
+   *   authKeyMap?          : Record<string, string>,
+   *   heartbeatInterval?   : number,
+   *   heartbeatTimeoutMs?  : number,
+   *   encrypted?           : boolean,
+   *   enablePayloadDigest? : boolean,
+   *   maxTimeSkewMs?       : number,
+   *   replayWindowMs?      : number,
    * }} options
    */
   constructor({
     role,
     id,
     endpoints = {},
-    maxPending = 0,
+    maxPending = DEFAULT_MAX_PENDING,
     authKey = "",
+    authKeyMap = null,
     heartbeatInterval = DEFAULT_HEARTBEAT_INTERVAL,
+    heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS,
     encrypted = false,
+    enablePayloadDigest = DEFAULT_ENABLE_PAYLOAD_DIGEST,
     maxTimeSkewMs = MAX_TIME_SKEW_MS,
     replayWindowMs = REPLAY_WINDOW_MS,
   } = {}) {
@@ -207,16 +228,35 @@ export class ZNL extends EventEmitter {
     this.endpoints = { ...DEFAULT_ENDPOINTS, ...endpoints };
     this.authKey = authKey == null ? "" : String(authKey);
 
+    if (this.role === "master") {
+      if (authKeyMap != null) {
+        if (typeof authKeyMap !== "object") {
+          throw new TypeError(
+            "`authKeyMap` 必须是对象（slaveId -> authKey）。",
+          );
+        }
+        for (const [slaveId, key] of Object.entries(authKeyMap)) {
+          if (key == null) continue;
+          this.#authKeyMap.set(String(slaveId), String(key));
+        }
+      }
+    }
+
     this.encrypted = Boolean(encrypted);
     this.#secureEnabled = this.encrypted;
 
     if (this.#secureEnabled) {
-      if (!this.authKey) {
-        throw new Error("启用 encrypted=true 时，必须提供非空 authKey。");
+      const hasAuthMap = this.role === "master" && authKeyMap != null;
+      if (!this.authKey && !hasAuthMap) {
+        throw new Error(
+          "启用 encrypted=true 时，必须提供非空 authKey 或 authKeyMap。",
+        );
+      }
+      if (this.authKey) {
+        const { signKey, encryptKey } = deriveKeys(this.authKey);
+        this.#signKey = signKey;
+        this.#encryptKey = encryptKey;
       }
-      const { signKey, encryptKey } = deriveKeys(this.authKey);
-      this.#signKey = signKey;
-      this.#encryptKey = encryptKey;
     }
 
     this.#pending = new PendingManager(maxPending);
@@ -224,6 +264,15 @@ export class ZNL extends EventEmitter {
     this.#heartbeatInterval =
       this.#normalizeHeartbeatInterval(heartbeatInterval);
 
+    // 是否启用 payload 摘要校验（安全模式用）
+    this.#enablePayloadDigest = Boolean(enablePayloadDigest);
+
+    // 心跳超时：<=0 则由 heartbeatInterval 推导
+    this.#heartbeatTimeoutMs = this.#normalizePositiveInt(
+      heartbeatTimeoutMs,
+      DEFAULT_HEARTBEAT_TIMEOUT_MS,
+    );
+
     this.#maxTimeSkewMs = this.#normalizePositiveInt(
       maxTimeSkewMs,
       MAX_TIME_SKEW_MS,
@@ -334,19 +383,34 @@ export class ZNL extends EventEmitter {
     if (this.#slaves.size === 0) return;
 
     const topicText = String(topic);
-    const payloadFrames = this.#sealPayloadFrames(
-      "publish",
-      topicText,
-      payload,
-    );
-    const authProof = this.#secureEnabled
-      ? this.#createAuthProof("publish", topicText, payloadFrames)
-      : "";
-
-    const frames = buildPublishFrames(topicText, payloadFrames, authProof);
 
     for (const [slaveId, entry] of this.#slaves) {
+      const keys = this.#secureEnabled ? this.#resolveSlaveKeys(slaveId) : null;
+      if (this.#secureEnabled && !keys) {
+        if (this.#slaves.delete(slaveId)) {
+          this.emit("slave_disconnected", slaveId);
+        }
+        continue;
+      }
+
+      const payloadFrames = this.#sealPayloadFrames(
+        "publish",
+        topicText,
+        payload,
+        keys?.encryptKey ?? null,
+      );
+      const authProof = this.#secureEnabled
+        ? this.#createAuthProof(
+            "publish",
+            topicText,
+            payloadFrames,
+            keys.signKey,
+          )
+        : "";
+
+      const frames = buildPublishFrames(topicText, payloadFrames, authProof);
       const idFrame = identityToBuffer(entry.identity);
+
       this.#sendQueue
         .enqueue("router", () => socket.send([idFrame, ...frames]))
         .catch(() => {
@@ -402,6 +466,63 @@ export class ZNL extends EventEmitter {
     return [...this.#slaves.keys()];
   }
 
+  /**
+   * 【Master 侧】动态添加/更新某个 slave 的 authKey（立即生效）
+   * @param {string} slaveId
+   * @param {string} authKey
+   * @returns {this}
+   */
+  addAuthKey(slaveId, authKey) {
+    if (this.role !== "master") {
+      throw new Error("addAuthKey() 只能在 master 侧调用。");
+    }
+    const id = String(slaveId ?? "");
+    if (!id) {
+      throw new Error("slaveId 不能为空。");
+    }
+    const key = authKey == null ? "" : String(authKey);
+    if (!key) {
+      throw new Error("authKey 不能为空。");
+    }
+
+    this.#authKeyMap.set(id, key);
+
+    if (this.#secureEnabled) {
+      const derived = deriveKeys(key);
+      this.#slaveKeyCache.set(id, derived);
+      const entry = this.#slaves.get(id);
+      if (entry) {
+        entry.signKey = derived.signKey;
+        entry.encryptKey = derived.encryptKey;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * 【Master 侧】移除某个 slave 的 authKey（立即生效）
+   * @param {string} slaveId
+   * @returns {this}
+   */
+  removeAuthKey(slaveId) {
+    if (this.role !== "master") {
+      throw new Error("removeAuthKey() 只能在 master 侧调用。");
+    }
+    const id = String(slaveId ?? "");
+    if (!id) {
+      throw new Error("slaveId 不能为空。");
+    }
+
+    this.#authKeyMap.delete(id);
+    this.#slaveKeyCache.delete(id);
+
+    if (this.#slaves.has(id)) {
+      this.#slaves.delete(id);
+      this.emit("slave_disconnected", id);
+    }
+    return this;
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════
   //  生命周期内部实现
   // ═══════════════════════════════════════════════════════════════════════════
@@ -464,6 +585,7 @@ export class ZNL extends EventEmitter {
     this.#sockets = {};
     this.#sendQueue.clear();
     this.#slaves.clear();
+    this.#slaveKeyCache.clear();
     this.#masterNodeId = null;
     this.#replayGuard.clear();
   }
@@ -476,7 +598,7 @@ export class ZNL extends EventEmitter {
    * 初始化 Master 侧 ROUTER socket（bind 模式），并启动读循环和死节点扫描定时器
    */
   async #startMasterSockets() {
-    const router = new zmq.Router();
+    const router = new zmq.Router({ handover: true });
     await router.bind(this.endpoints.router);
     this.#sockets.router = router;
 
@@ -533,41 +655,80 @@ export class ZNL extends EventEmitter {
     // ── 心跳 ────────────────────────────────────────────────────────────────
     if (parsed.kind === "heartbeat") {
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "heartbeat",
           proofToken: parsed.authProof,
           requestId: "",
           payloadFrames: [],
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
           return;
         }
+
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
+        return;
       }
 
-      const entry = this.#slaves.get(identityText);
-      if (entry) entry.lastSeen = Date.now();
+      // 心跳视为在线确认：必要时自动补注册
+      this.#ensureSlaveOnline(identityText, identity, { touch: true });
       return;
     }
 
     // ── 注册 ────────────────────────────────────────────────────────────────
     if (parsed.kind === "register") {
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "register",
           proofToken: parsed.authKey, // register 复用 authKey 字段承载 proof
           requestId: "",
           payloadFrames: [],
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
           return;
         }
+
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
+        return;
       }
 
-      this.#slaves.set(identityText, { identity, lastSeen: Date.now() });
+      this.#slaves.set(identityText, {
+        identity,
+        lastSeen: Date.now(),
+        signKey: null,
+        encryptKey: null,
+      });
       this.emit("slave_connected", identityText);
       return;
     }
@@ -585,18 +746,35 @@ export class ZNL extends EventEmitter {
       let finalFrames = parsed.payloadFrames;
 
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "request",
           proofToken: parsed.authKey, // request 复用 authKey 字段承载 proof
           requestId: parsed.requestId,
           payloadFrames: parsed.payloadFrames,
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
           return;
         }
 
+        // 认证通过后允许补注册（避免 master 重启后丢失在线表）
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
+
         if (this.encrypted) {
           try {
             finalFrames = this.#openPayloadFrames(
@@ -604,6 +782,7 @@ export class ZNL extends EventEmitter {
               parsed.requestId,
               parsed.payloadFrames,
               identityText,
+              keys.encryptKey,
             );
           } catch (error) {
             this.#emitAuthFailed(
@@ -613,6 +792,9 @@ export class ZNL extends EventEmitter {
             return;
           }
         }
+      } else {
+        // 明文模式同样补注册
+        this.#ensureSlaveOnline(identityText, identity, { touch: true });
       }
 
       const finalPayload = payloadFromFrames(finalFrames);
@@ -635,18 +817,35 @@ export class ZNL extends EventEmitter {
       let finalFrames = parsed.payloadFrames;
 
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "response",
           proofToken: parsed.authProof,
           requestId: parsed.requestId,
           payloadFrames: parsed.payloadFrames,
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
           return;
         }
 
+        // 认证通过后允许补注册（避免 master 重启后丢失在线表）
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
+
         if (this.encrypted) {
           try {
             finalFrames = this.#openPayloadFrames(
@@ -654,6 +853,7 @@ export class ZNL extends EventEmitter {
               parsed.requestId,
               parsed.payloadFrames,
               identityText,
+              keys.encryptKey,
             );
           } catch (error) {
             this.#emitAuthFailed(
@@ -663,6 +863,9 @@ export class ZNL extends EventEmitter {
             return;
           }
         }
+      } else {
+        // 明文模式同样补注册
+        this.#ensureSlaveOnline(identityText, identity, { touch: true });
       }
 
       const finalPayload = payloadFromFrames(finalFrames);
@@ -893,13 +1096,21 @@ export class ZNL extends EventEmitter {
       identityText,
     );
 
+    const keys = this.#secureEnabled
+      ? this.#resolveSlaveKeys(identityText)
+      : null;
+    if (this.#secureEnabled && !keys) {
+      throw new Error(`未配置该 slave 的 authKey：${identityText}`);
+    }
+
     const payloadFrames = this.#sealPayloadFrames(
       "request",
       requestId,
       payload,
+      keys?.encryptKey ?? null,
     );
     const proofOrAuthKey = this.#secureEnabled
-      ? this.#createAuthProof("request", requestId, payloadFrames)
+      ? this.#createAuthProof("request", requestId, payloadFrames, keys.signKey)
       : "";
 
     const frames = buildRequestFrames(requestId, payloadFrames, proofOrAuthKey);
@@ -947,15 +1158,29 @@ export class ZNL extends EventEmitter {
    */
   async #replyTo(identity, requestId, payload) {
     const socket = this.#requireSocket("router", "ROUTER");
+    const identityText = identityToString(identity);
     const idFrame = identityToBuffer(identity);
 
+    const keys = this.#secureEnabled
+      ? this.#resolveSlaveKeys(identityText)
+      : null;
+    if (this.#secureEnabled && !keys) {
+      throw new Error(`未配置该 slave 的 authKey：${identityText}`);
+    }
+
     const payloadFrames = this.#sealPayloadFrames(
       "response",
       requestId,
       payload,
+      keys?.encryptKey ?? null,
     );
     const authProof = this.#secureEnabled
-      ? this.#createAuthProof("response", requestId, payloadFrames)
+      ? this.#createAuthProof(
+          "response",
+          requestId,
+          payloadFrames,
+          keys.signKey,
+        )
       : "";
 
     const frames = buildResponseFrames(requestId, payloadFrames, authProof);
@@ -998,7 +1223,11 @@ export class ZNL extends EventEmitter {
   #startHeartbeatCheck() {
     if (this.#heartbeatInterval <= 0) return;
 
-    const timeout = this.#heartbeatInterval * 3;
+    // 心跳超时：优先使用配置值，<=0 则回退到 interval × 3
+    const timeout =
+      this.#heartbeatTimeoutMs > 0
+        ? this.#heartbeatTimeoutMs
+        : this.#heartbeatInterval * 3;
 
     this.#heartbeatCheckTimer = setInterval(() => {
       const now = Date.now();
@@ -1023,8 +1252,9 @@ export class ZNL extends EventEmitter {
    * @param {Buffer[]} payloadFrames
    * @returns {string}
    */
-  #createAuthProof(kind, requestId, payloadFrames) {
-    if (!this.#secureEnabled || !this.#signKey) return "";
+  #createAuthProof(kind, requestId, payloadFrames, signKeyOverride = null) {
+    const signKey = signKeyOverride ?? this.#signKey;
+    if (!this.#secureEnabled || !signKey) return "";
 
     const envelope = {
       kind: String(kind),
@@ -1032,13 +1262,16 @@ export class ZNL extends EventEmitter {
       requestId: String(requestId ?? ""),
       timestamp: nowMs(),
       nonce: generateNonce(),
-      payloadDigest: digestFrames(payloadFrames),
+      // 可选 payload 摘要：关闭时写空串以提升性能
+      payloadDigest: this.#enablePayloadDigest
+        ? digestFrames(payloadFrames)
+        : "",
     };
 
     // 保留 canonical 文本，便于后续排障（签名实际在 token 内完成）
     canonicalSignInput(envelope);
 
-    return encodeAuthProofToken(this.#signKey, envelope);
+    return encodeAuthProofToken(signKey, envelope);
   }
 
   /**
@@ -1059,9 +1292,12 @@ export class ZNL extends EventEmitter {
     requestId,
     payloadFrames,
     expectedNodeId = null,
+    signKey = null,
   }) {
     if (!this.#secureEnabled) return { ok: true, envelope: null };
-    if (!this.#signKey) {
+
+    const verifyKey = signKey ?? this.#signKey;
+    if (!verifyKey) {
       return { ok: false, error: "签名密钥未初始化。" };
     }
 
@@ -1069,7 +1305,7 @@ export class ZNL extends EventEmitter {
       return { ok: false, error: "缺少认证证明（proofToken）。" };
     }
 
-    const decoded = decodeAuthProofToken(this.#signKey, proofToken, {
+    const decoded = decodeAuthProofToken(verifyKey, proofToken, {
       maxSkewMs: this.#maxTimeSkewMs,
       now: Date.now(),
     });
@@ -1100,12 +1336,15 @@ export class ZNL extends EventEmitter {
       };
     }
 
-    const currentDigest = digestFrames(payloadFrames);
-    if (String(envelope.payloadDigest) !== currentDigest) {
-      return { ok: false, error: "payload 摘要不一致，疑似篡改。" };
+    if (this.#enablePayloadDigest) {
+      const currentDigest = digestFrames(payloadFrames);
+      if (String(envelope.payloadDigest) !== currentDigest) {
+        return { ok: false, error: "payload 摘要不一致，疑似篡改。" };
+      }
     }
 
-    const replayKey = `${envelope.kind}|${envelope.nodeId}|${envelope.nonce}`;
+    // 重放 key 加入 requestId，降低 nonce 碰撞误杀风险
+    const replayKey = `${envelope.kind}|${envelope.nodeId}|${envelope.requestId}|${envelope.nonce}`;
     if (this.#replayGuard.seenOrAdd(replayKey)) {
       return { ok: false, error: "检测到重放请求（nonce 重复）。" };
     }
@@ -1123,13 +1362,14 @@ export class ZNL extends EventEmitter {
    * @param {*} payload
    * @returns {Buffer[]}
    */
-  #sealPayloadFrames(kind, requestId, payload) {
+  #sealPayloadFrames(kind, requestId, payload, encryptKeyOverride = null) {
     if (!this.encrypted) {
       // 非加密模式保持历史行为：沿用协议层的原始帧类型（string/Buffer）
       return normalizeFrames(payload);
     }
 
-    if (!this.#encryptKey) {
+    const encryptKey = encryptKeyOverride ?? this.#encryptKey;
+    if (!encryptKey) {
       throw new Error("加密密钥未初始化。");
     }
 
@@ -1139,11 +1379,7 @@ export class ZNL extends EventEmitter {
       "utf8",
     );
 
-    const { iv, ciphertext, tag } = encryptFrames(
-      this.#encryptKey,
-      rawFrames,
-      aad,
-    );
+    const { iv, ciphertext, tag } = encryptFrames(encryptKey, rawFrames, aad);
 
     // 用统一信封包装：version + iv + tag + ciphertext
     return [Buffer.from(SECURITY_ENVELOPE_VERSION), iv, tag, ciphertext];
@@ -1160,9 +1396,16 @@ export class ZNL extends EventEmitter {
    * @param {string} senderNodeId
    * @returns {Buffer[]}
    */
-  #openPayloadFrames(kind, requestId, payloadFrames, senderNodeId) {
+  #openPayloadFrames(
+    kind,
+    requestId,
+    payloadFrames,
+    senderNodeId,
+    encryptKeyOverride = null,
+  ) {
     if (!this.encrypted) return payloadFrames;
-    if (!this.#encryptKey) throw new Error("加密密钥未初始化。");
+    const encryptKey = encryptKeyOverride ?? this.#encryptKey;
+    if (!encryptKey) throw new Error("加密密钥未初始化。");
 
     if (!Array.isArray(payloadFrames) || payloadFrames.length !== 4) {
       throw new Error("加密信封格式非法：期望 4 帧。");
@@ -1178,7 +1421,7 @@ export class ZNL extends EventEmitter {
       "utf8",
     );
 
-    return decryptFrames(this.#encryptKey, iv, ciphertext, tag, aad);
+    return decryptFrames(encryptKey, iv, ciphertext, tag, aad);
   }
 
   /**
@@ -1194,6 +1437,76 @@ export class ZNL extends EventEmitter {
     });
   }
 
+  /**
+   * master 侧确保某个 slave 已登记在线
+   * - 仅在认证通过后调用
+   * - 支持心跳/请求/响应等路径的自动补注册
+   *
+   * @param {string} identityText
+   * @param {Buffer|string|Uint8Array} identity
+   * @param {{ touch?: boolean }} [options]
+   */
+  #ensureSlaveOnline(
+    identityText,
+    identity,
+    { touch = true, signKey = null, encryptKey = null } = {},
+  ) {
+    const id = String(identityText ?? "");
+    if (!id) return;
+
+    const now = Date.now();
+    const entry = this.#slaves.get(id);
+    if (entry) {
+      if (touch) entry.lastSeen = now;
+      if (signKey) entry.signKey = signKey;
+      if (encryptKey) entry.encryptKey = encryptKey;
+      return;
+    }
+
+    this.#slaves.set(id, {
+      identity: identityToBuffer(identity),
+      lastSeen: now,
+      signKey: signKey ?? null,
+      encryptKey: encryptKey ?? null,
+    });
+    this.emit("slave_connected", id);
+  }
+
+  /**
+   * master 侧解析某个 slave 的签名/加密密钥
+   * - 优先匹配 authKeyMap
+   * - 未命中时回退到 this.authKey（若提供）
+   *
+   * @param {string} slaveId
+   * @returns {{ signKey: Buffer, encryptKey: Buffer }|null}
+   */
+  #resolveSlaveKeys(slaveId) {
+    if (!this.#secureEnabled) return null;
+
+    const id = String(slaveId ?? "");
+    if (!id) return null;
+
+    const cached = this.#slaveKeyCache.get(id);
+    if (cached) return cached;
+
+    let key = this.#authKeyMap.get(id);
+    if (!key && this.authKey) {
+      key = this.authKey;
+    }
+    if (!key) return null;
+
+    const derived = deriveKeys(key);
+    this.#slaveKeyCache.set(id, derived);
+
+    const entry = this.#slaves.get(id);
+    if (entry) {
+      entry.signKey = derived.signKey;
+      entry.encryptKey = derived.encryptKey;
+    }
+
+    return derived;
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════
   //  工具方法
   // ═══════════════════════════════════════════════════════════════════════════

package/src/constants.js

@@ -36,6 +36,15 @@ export const DEFAULT_TIMEOUT_MS = 5000;
 /** 默认心跳间隔（毫秒），0 表示禁用心跳 */
 export const DEFAULT_HEARTBEAT_INTERVAL = 3000;
 
+/** 默认心跳超时时间（毫秒），0 表示采用 heartbeatInterval × 3 */
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 0;
+
+/** 默认最大并发请求数（0 表示不限制） */
+export const DEFAULT_MAX_PENDING = 1000;
+
+/** 默认是否启用 payload 摘要（安全模式用） */
+export const DEFAULT_ENABLE_PAYLOAD_DIGEST = true;
+
 /** 默认端点配置 */
 export const DEFAULT_ENDPOINTS = {
   router: "tcp://127.0.0.1:6003",

package/src/security.js

@@ -385,11 +385,29 @@ export function decodeAuthProofToken(
 
 /**
  * 计算 payload 帧摘要（sha256 hex）
+ * 说明：按协议顺序增量写入，避免一次性拼接大 Buffer
  * @param {Buffer[]} frames
  * @returns {string}
  */
 export function digestFrames(frames) {
-  return createHash("sha256").update(encodeFrames(frames)).digest("hex");
+  const safeFrames = Array.isArray(frames) ? frames : [];
+  const hash = createHash("sha256");
+
+  // 写入帧数量（u32be）
+  const head = Buffer.allocUnsafe(4);
+  head.writeUInt32BE(safeFrames.length, 0);
+  hash.update(head);
+
+  // 逐帧写入长度与内容（u32be + bytes）
+  for (const frame of safeFrames) {
+    const buf = toBuffer(frame);
+    const len = Buffer.allocUnsafe(4);
+    len.writeUInt32BE(buf.length, 0);
+    hash.update(len);
+    if (buf.length > 0) hash.update(buf);
+  }
+
+  return hash.digest("hex");
 }
 
 /**