dsh-lan-peers 0.7.2 → 0.7.4

package/host/test/group-cluster.mjs

@@ -89,6 +89,12 @@ export async function startCluster(t, options = {}) {
     commitTimeoutMs: commitOverride = commitTimeoutMs,
     tickMs: tickOverride = tickMs,
     jitterMs = 0,
+    // S3 补充：哪些下标是「hub 角色」（配置上没有 group.hub，可参与启动接管）。默认只有 0。
+    hubRoles = [0],
+    // 预置角色文件：{ 下标: leader 下标 } → 该节点以 follower 起步（leader 指向另一台）
+    followerOf = {},
+    // 假时钟（「推进 30s 验证不再重试」这类断言用）
+    now: nowOverride = null,
   } = options;
 
   const ids = customIds ?? Array.from({ length: count }, (_, index) => `peer-s3-${String.fromCharCode(97 + index)}`);
@@ -106,9 +112,46 @@ export async function startCluster(t, options = {}) {
 
   const nodes = [];
   const urls = [];
+  const hubRoleIndexes = new Set(hubRoles);
+  hubRoleIndexes.add(0);
+  /** node0 的群快照：后面的 hub 角色节点要复用同一 groupId/groupKey */
+  let hubSnapshot = null;
   for (let index = 0; index < count; index += 1) {
     // 先写 peers.json 再 listen：成员启动那一轮就能解析到 hub
     writePeersJson(dirs[index], ids, names, urls, index);
+    const isHubRole = hubRoleIndexes.has(index);
+    if (index > 0 && isHubRole && hubSnapshot) {
+      // 第二个 hub 角色节点：先把 group.json 写成与 node0 同一把群密钥/groupId，
+      // 否则 GroupStore 首次 load 会自己生成一份新的（那就不是一个群了）
+      const members = {};
+      for (let other = 0; other < index; other += 1) {
+        members[ids[other]] = { name: names[other], baseUrl: urls[other], addedAt: new Date().toISOString() };
+      }
+      members[ids[index]] = { name: names[index], addedAt: new Date().toISOString() };
+      writeJson0600(path.join(dirs[index], 'group.json'), {
+        groupId: hubSnapshot.groupId,
+        key: hubSnapshot.groupKey,
+        keyVersion: hubSnapshot.epoch,
+        name: hubSnapshot.name,
+        createdAt: new Date().toISOString(),
+        members,
+        messages: [],
+        pending: [],
+        lastSeq: 0,
+      });
+    }
+    if (index in followerOf) {
+      // 预置角色文件：以 follower 起步（leader 指向 followerOf[index] 那台）
+      writeJson0600(path.join(dirs[index], 'group-role.json'), {
+        role: 'follower',
+        epoch: hubSnapshot ? hubSnapshot.epoch : 1,
+        leaderPeerId: ids[followerOf[index]],
+        leaseUntil: Date.now() + 60_000,
+        commitSeq: 0,
+        votedFor: null,
+        groupId: hubSnapshot ? hubSnapshot.groupId : '',
+      });
+    }
     const group = {
       enabled: true,
       name: 's3',
@@ -119,11 +162,12 @@ export async function startCluster(t, options = {}) {
       commitTimeoutMs: commitOverride,
       hubPriority: priorities[index] ?? 0,
     };
-    if (index > 0) group.hub = names[0];
+    if (!isHubRole) group.hub = names[0];
     const server = createPeerServer({
       listenHost: '127.0.0.1',
       stateDir: dirs[index],
       requireEncryption,
+      ...(nowOverride ? { now: nowOverride } : {}),
       allowRemotePrompts: true,
       logger,
       group,
@@ -140,6 +184,11 @@ export async function startCluster(t, options = {}) {
     const info = await server.listen(0, '127.0.0.1');
     server.config.group.advertiseBaseUrl = info.url;
     urls[index] = info.url;
+    if (isHubRole) {
+      const self = server.group.state().members[ids[index]];
+      if (self) self.baseUrl = info.url;
+      if (!hubSnapshot) hubSnapshot = server.group.state({ includeKey: true });
+    }
     nodes.push({
       index,
       peerId: ids[index],
@@ -160,6 +209,16 @@ export async function startCluster(t, options = {}) {
     hub.server.group.state().members[ids[index]].baseUrl = urls[index];
   }
 
+  // 第二个及以后的 hub 角色节点：成员表补齐（自己那条地址在 listen 后已写）
+  for (const node of nodes.slice(1)) {
+    if (!node.server.group.isHub) continue;
+    for (let index = 0; index < count; index += 1) {
+      if (index === node.index) continue;
+      node.server.group.addMember(ids[index], names[index]);
+      node.server.group.state().members[ids[index]].baseUrl = urls[index];
+    }
+  }
+
   const snapshot = hub.server.group.state({ includeKey: true });
   for (let index = 1; index < count; index += 1) {
     const members = {};

package/host/test/group-commit.test.mjs

@@ -49,6 +49,8 @@ test('S3 majority：propose→commit 全链路，三台都可见且 commitSeq
   assert.equal(a.server.group.state().pendingCount, 0, '提交后 pending 必须清空');
 
   // 日志：一行 post、一行 commit、至少一次心跳；不含正文/密钥
+  // 心跳按 heartbeatMs（默认 120ms）广播，用例本身只要 ~200ms —— 必须**等事件**，不能靠时序。
+  await waitFor(() => lines.some((line) => line.startsWith('[group] heartbeat ')), { timeoutMs: 3_000 });
   const logText = lines.join('\n');
   assert.match(logText, /\[group\] post kind=chat seq=1 /);
   assert.match(logText, /\[group\] commit seq=1 /);
@@ -203,7 +205,8 @@ test('S3 seq 连续无重复：失败的提案不消耗号，恢复后重试拿
   assert.equal(first.status, 201);
   assert.equal(first.json.seq, 1);
 
-  // 把两台成员的地址改成打不通：只拿得到自己一票 → 503
+  // 把两台成员的地址改成打不通：只拿得到自己一票 → 503。
+  // 群成员表里的 baseUrl 是权威寻址（baseUrlOf 优先读它），所以这里改完立刻生效。
   const members = a.server.group.state().members;
   members[b.peerId].baseUrl = 'http://127.0.0.1:1';
   members[c.peerId].baseUrl = 'http://127.0.0.1:1';
@@ -264,6 +267,50 @@ test('S3 成员当 leader 且要求加密时：post 走 X-Peer-Enc 也能两阶
   // hub 侧靠 commit 转正（加密通道同理）
   await waitFor(() => a.server.group.history({ sinceSeq: 0 }).length === 1);
 });
+test('S3 取号闸门：pending 占着的号不会被单阶段写（面板/管理接口）复用', async (t) => {
+  const cluster = await startCluster(t, { count: 3, commitTimeoutMs: 2_000 });
+  const [a, b, c] = cluster.nodes;
+  // 黑洞：提案会一直挂在 pending 里，直到 commitTimeoutMs 才丢弃
+  const sockets = new Set();
+  const blackhole = net.createServer((socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+    socket.on('error', () => sockets.delete(socket));
+  });
+  await new Promise((resolve) => blackhole.listen(0, '127.0.0.1', resolve));
+  t.after(() => {
+    for (const socket of sockets) socket.destroy();
+    blackhole.close();
+  });
+  blackhole.unref();
+  const holeUrl = `http://127.0.0.1:${blackhole.address().port}`;
+  const members = a.server.group.state().members;
+  members[b.peerId].baseUrl = holeUrl;
+  members[c.peerId].baseUrl = holeUrl;
+
+  const inflight = postAs(a.baseUrl, b.peerId, { kind: 'chat', text: 'slow-proposal' });
+  await waitFor(() => a.server.group.state().pendingCount === 1, { timeoutMs: 1_500 });
+  const pendingSeq = a.server.group.state().lastSeq + 1;
+  assert.equal(a.server.group.state().lastSeq, 0, '提案未提交，lastSeq 不推进');
+
+  // 面板/管理接口走单阶段写（server.group.post → GroupStore.append）：必须避开 pending 占的号
+  const panel = a.server.group.post({ peerId: 'peer-panel', name: 'panel', kind: 'chat', text: 'panel-msg' });
+  assert.equal(panel.seq, pendingSeq + 1, '单阶段写不得复用 pending 占着的 seq');
+
+  const failed = await inflight;
+  assert.equal(failed.status, 503, failed.text);
+  assert.equal(a.server.group.state().pendingCount, 0, '超时后 pending 必须清空');
+
+  // 恢复可达后继续写：号必须继续往前走，且任何两条消息不共用 seq
+  members[b.peerId].baseUrl = b.baseUrl;
+  members[c.peerId].baseUrl = c.baseUrl;
+  const next = await postAs(a.baseUrl, b.peerId, { kind: 'chat', text: 'after-drop' });
+  assert.equal(next.status, 201, next.text);
+  assert.equal(next.json.seq, panel.seq + 1);
+  const seqs = a.server.group.history({ sinceSeq: 0 }).map((m) => m.seq);
+  assert.deepEqual(seqs, [panel.seq, panel.seq + 1]);
+  assert.equal(new Set(seqs).size, seqs.length, 'seq 不得重复（客户端按 seq 去重）');
+});
 test('S3 提交串行化：连续多条 post 的 seq 严格连续（并发下也不撞号）', async (t) => {
   const cluster = await startCluster(t, { count: 3 });
   const [a, b] = cluster.nodes;

package/host/test/group-election.test.mjs

@@ -11,8 +11,11 @@ import fs from 'node:fs';
 import { setTimeout as sleep } from 'node:timers/promises';
 import {
   fetchGroupLease,
+  pullGroupMessages,
+  readGroupKeyFile,
   requestGroupVote,
   sendGroupHeartbeat,
+  writeGroupKeyFile,
 } from '../../lib/group-client.mjs';
 import { fileMode, makeTempStateDir } from './helpers.mjs';
 import { postAs, readRoleFile, roleOf, startCluster, waitFor } from './group-cluster.mjs';
@@ -362,7 +365,26 @@ test('S3 quorum 分母 = 成员表全集：没有任何地址的成员也计入
   for (const id of ['peer-ghost-1', 'peer-ghost-2', 'peer-ghost-3']) a.server.group.removeMember(id);
   const ok = await postAs(a.baseUrl, b.peerId, { kind: 'chat', text: 'ghost-gone' });
   assert.equal(ok.status, 201, ok.text);
-  assert.equal((await lease(a)).quorumNeeded, 2);
+  // 移除成员会轮换群密钥（keyVersion+1）：旧钥必须被拒，新钥照常
+  const rotated = a.server.group.state({ includeKey: true });
+  assert.ok(rotated.keyVersion > 1, 'removeMember 必须轮换 keyVersion');
+  assert.notEqual(rotated.groupKey, cluster.groupKey, '轮换后 groupKey 必须变化');
+  await assert.rejects(
+    () => fetchGroupLease({ baseUrl: a.baseUrl, groupKey: cluster.groupKey, groupId: cluster.groupId, senderId: b.peerId }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'bad-signature');
+      return true;
+    },
+  );
+  const after = await fetchGroupLease({
+    baseUrl: a.baseUrl,
+    groupKey: rotated.groupKey,
+    groupId: cluster.groupId,
+    senderId: b.peerId,
+  });
+  assert.equal(after.quorumNeeded, 2);
+  assert.equal(after.keyVersion, rotated.keyVersion, 'lease 必须暴露 keyVersion');
 });
 
 test('S3 单节点自立为 leader 必败：N=2 且另一台不可达 → quorum-unavailable', async (t) => {
@@ -399,6 +421,47 @@ test('S3 N=3：两台可达能当选（2 ≥ 2），只剩一台不能（1 < 2
   assert.equal(lonely.needed, 2);
   assert.notEqual(roleOf(c).role, 'leader');
 });
+test('S3 成员表未同步时：选举/心跳自愈入表（真机 not-a-member 的回归）', async (t) => {
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [a, b, c] = cluster.nodes;
+  // 造「c 的成员表来自一份不完整的快照」：把 b 从 c 的 group-key.json 里删掉
+  const keyFile = readGroupKeyFile(c.dir);
+  delete keyFile.members[b.peerId];
+  writeGroupKeyFile(c.dir, keyFile);
+  const stale = readGroupKeyFile(c.dir);
+  assert.equal(Boolean(stale.members[b.peerId]), false, '前提：c 不认识 b');
+
+  // b 拉票：原来会 401 not-a-member（对端永远投不进来 → 群选不出 leader）
+  const vote = await requestGroupVote({
+    baseUrl: c.baseUrl,
+    ...groupArgs(cluster, b.peerId),
+    epoch: 3,
+    candidate: b.peerId,
+  });
+  assert.equal(vote.vote, true, JSON.stringify(vote));
+  assert.equal(vote.epoch, 3);
+  // 自愈：c 把 b 补回成员表（并落盘）
+  const healed = readGroupKeyFile(c.dir);
+  assert.ok(healed.members[b.peerId], 'c 必须把 b 补回成员表并落盘');
+  // 第二次直接投，不再走自愈分支
+  const again = await requestGroupVote({
+    baseUrl: c.baseUrl,
+    ...groupArgs(cluster, b.peerId),
+    epoch: 4,
+    candidate: b.peerId,
+  });
+  assert.equal(again.vote, true);
+
+  // 非领导权路径仍然严格：成员表没有的发送方打 pull 仍 401 not-a-member（不自愈）
+  await assert.rejects(
+    () => pullGroupMessages({ baseUrl: c.baseUrl, ...groupArgs(cluster, 'peer-not-in-group') }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'not-a-member');
+      return true;
+    },
+  );
+});
 // 说明：post 走 per-peer 签名，这里顺带确认 leader 真的能收（详情见 group-commit.test.mjs）
 test('S3 leader 就绪：hub leader 的 post 通道可用（202/201 由 commit 测试覆盖）', async (t) => {
   const cluster = await startCluster(t, { count: 2, quorum: 'none' });

package/host/test/group-key-rotation.test.mjs

@@ -0,0 +1,219 @@
+/**
+ * v0.7.3 安全硬化 · 移除成员即轮换群密钥 + 成员侧换钥自愈（契约补充）。
+ *
+ * 两个洞的回归：
+ *  ① hub 收到「不在成员表但握着有效 groupKey」的心跳时必须拒绝，且**不得**把它写回成员表
+ *  ② removeMember 必须轮换 keyVersion；被移除者的旧钥一律 401 bad-signature
+ * 另外两条保护：③成员侧换钥后自动重试一次 ④成员侧（副本）自愈仍然有效
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { setTimeout as sleep } from 'node:timers/promises';
+import {
+  fetchGroupLease,
+  readGroupKeyFile,
+  requestGroupVote,
+  sendGroupHeartbeat,
+  writeGroupKeyFile,
+} from '../../lib/group-client.mjs';
+import { postAs, roleOf, startCluster, waitFor } from './group-cluster.mjs';
+
+const groupArgs = (cluster, senderId) => ({
+  groupKey: cluster.groupKey,
+  groupId: cluster.groupId,
+  senderId,
+});
+
+test('① hub 永不自愈：持有有效 groupKey 但不在成员表 → 401 not-a-member，且不写回成员表', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub] = cluster.nodes;
+  const before = Object.keys(hub.server.group.state().members).sort();
+  const outsider = 'peer-not-invited-9f3a';
+
+  const heartbeat = await assert.rejects(
+    () => sendGroupHeartbeat({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, outsider),
+      epoch: 1,
+      leaderPeerId: outsider,
+    }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'not-a-member');
+      return true;
+    },
+  );
+  assert.equal(heartbeat, undefined);
+  // 投票端点同样是领导权协议，但 hub 侧也不得自愈
+  await assert.rejects(
+    () => requestGroupVote({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, outsider),
+      epoch: 2,
+      candidate: outsider,
+    }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'not-a-member');
+      return true;
+    },
+  );
+  assert.deepEqual(Object.keys(hub.server.group.state().members).sort(), before, 'group.json 的成员表不得被自愈写入');
+  assert.equal(readGroupKeyFile(hub.dir), null, 'hub 不写 group-key.json');
+});
+
+test('② 移除成员即轮换密钥：keyVersion+1，被移除者用旧钥打 election/leader → 401 bad-signature', async (t) => {
+  const lines = [];
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000, logger: (line) => lines.push(String(line)) });
+  const [hub, , removed] = cluster.nodes;
+  const before = hub.server.group.state({ includeKey: true });
+  assert.equal(before.keyVersion, 1);
+
+  assert.equal(hub.server.group.removeMember(removed.peerId), true);
+  const after = hub.server.group.state({ includeKey: true });
+  assert.equal(after.keyVersion, before.keyVersion + 1, '移除成员必须抬 keyVersion');
+  assert.notEqual(after.groupKey, before.groupKey, '必须换一把新 groupKey');
+  assert.equal(after.members[removed.peerId], undefined, '成员表里不能再有它');
+  // 日志：一行摘要，且绝不打印密钥本身
+  const rotatedLine = lines.find((line) => line.startsWith('[group] key rotated '));
+  assert.ok(rotatedLine, '必须有 [group] key rotated 日志');
+  assert.match(rotatedLine, new RegExp(`keyVersion=${after.keyVersion} reason=member-removed`));
+  assert.equal(rotatedLine.includes(after.groupKey), false, '日志不得打印密钥');
+  assert.equal(rotatedLine.includes(before.groupKey), false, '日志不得打印旧密钥');
+  if (process.platform !== 'win32') {
+    const mode = (await import('node:fs')).statSync(hub.server.group.state ? hub.dir + '/group.json' : '').mode & 0o777;
+    assert.equal(mode, 0o600, 'group.json 仍必须 0600');
+  }
+
+  // 被移除者仍握着旧钥（它的 group-key.json 没变）→ 一律拒绝，且**不是** not-a-member。
+  // 有 body 的请求（心跳/投票）在信封层就先炸：400 bad-encryption；
+  // 无 body 的请求（GET /v1/group/lease）能走到验签：401 bad-signature。两者都证明旧钥已失效。
+  const rejectedWithOldKey = (error) => {
+    assert.equal(error.status === 401 || error.status === 400, true, '状态必须是 401/400，实际 ' + error.status);
+    assert.equal(['bad-signature', 'bad-encryption'].includes(String(error.code)), true, '错误码 ' + error.code);
+    assert.notEqual(String(error.code), 'not-a-member', '不能只是 not-a-member —— 说明密钥没轮换');
+    return true;
+  };
+  await assert.rejects(
+    () => sendGroupHeartbeat({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, removed.peerId),
+      epoch: 2,
+      leaderPeerId: removed.peerId,
+    }),
+    rejectedWithOldKey,
+  );
+  await assert.rejects(
+    () => requestGroupVote({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, removed.peerId),
+      epoch: 2,
+      candidate: removed.peerId,
+    }),
+    rejectedWithOldKey,
+  );
+  // 无 body 的那条给出精确的 401 bad-signature（验签先于成员表检查）
+  await assert.rejects(
+    () => fetchGroupLease({
+      baseUrl: hub.baseUrl,
+      ...groupArgs(cluster, removed.peerId),
+    }),
+    (error) => {
+      assert.equal(error.status, 401);
+      assert.equal(error.code, 'bad-signature');
+      return true;
+    },
+  );
+  // hub 侧不再把它算进多数派分母
+  const lease = await fetchGroupLease({
+    baseUrl: hub.baseUrl,
+    groupKey: after.groupKey,
+    groupId: cluster.groupId,
+    senderId: cluster.nodes[1].peerId,
+  });
+  assert.equal(lease.memberCount, 2);
+  assert.equal(lease.keyVersion, after.keyVersion);
+});
+
+test('②b 被移除的成员不能靠自助 join 回来（同一个洞的另一扇门）', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub, member] = cluster.nodes;
+  assert.equal(hub.server.group.state().members[member.peerId] !== undefined, true);
+  hub.server.group.removeMember(member.peerId);
+  // 成员用 per-peer 签名打 /v1/group/join（autoJoin 是开的）——原来会被加回成员表
+  const res = await postAs(hub.baseUrl, member.peerId, { name: 'sneak-back' }, { path: '/v1/group/join' });
+  assert.equal(res.status, 403, res.text);
+  assert.equal(res.json.error, 'not-a-member');
+  assert.equal(hub.server.group.state().members[member.peerId], undefined, '成员表不得被 join 写回');
+  // 运维显式重新邀请（addMember）会解除 blocked，之后 join 也恢复正常语义
+  hub.server.group.addMember(member.peerId, 'node-b');
+  assert.equal(hub.server.group.state().members[member.peerId] !== undefined, true);
+});
+test('③ 成员换钥：hub 轮换后首次请求被拒 → 自动 refetch state → 重试一次成功', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub, member] = cluster.nodes;
+  // 让 hub 轮换密钥，但 member 仍在成员表里（模拟「踢掉第三台」后的换钥）
+  hub.server.group.addMember('peer-ghost-1', 'ghost');
+  hub.server.group.removeMember('peer-ghost-1');
+  const rotated = hub.server.group.state({ includeKey: true });
+  assert.ok(rotated.keyVersion > 1);
+  assert.notEqual(readGroupKeyFile(member.dir)?.key, rotated.groupKey, '前提：成员手里还是旧钥');
+  assert.equal(hub.server.group.members().some((entry) => entry.peerId === member.peerId), true);
+
+  // 成员的下一次出站群请求（拉补差）会先撞 401 bad-signature → 换钥 → 重试一次
+  let out = await member.server.group.pull();
+  for (let attempt = 0; attempt < 40 && out?.reason === 'skipped'; attempt += 1) {
+    await sleep(25);
+    out = await member.server.group.pull();
+  }
+  assert.equal(out.ok, true, JSON.stringify(out));
+  const refreshed = readGroupKeyFile(member.dir);
+  assert.equal(refreshed.key, rotated.groupKey, '成员必须把新钥落进 group-key.json');
+  assert.equal(roleOf(member).keyVersion, rotated.keyVersion, 'role() 必须暴露新 keyVersion');
+  // 只重试一次：再拉一次应当直接成功
+  const second = await member.server.group.pull();
+  assert.equal(second.ok, true);
+});
+
+test('④ 成员侧（副本）自愈仍然有效：表未同步但未移除的成员，election 仍被接受并补表', async (t) => {
+  const cluster = await startCluster(t, { count: 3, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [, b, c] = cluster.nodes;
+  // 造「c 的成员表来自不完整快照」：把 b 从 c 的 group-key.json 里删掉
+  const keyFile = readGroupKeyFile(c.dir);
+  delete keyFile.members[b.peerId];
+  writeGroupKeyFile(c.dir, keyFile);
+  assert.equal(Boolean(readGroupKeyFile(c.dir).members[b.peerId]), false);
+
+  const vote = await requestGroupVote({
+    baseUrl: c.baseUrl,
+    ...groupArgs(cluster, b.peerId),
+    epoch: 3,
+    candidate: b.peerId,
+  });
+  assert.equal(vote.vote, true, JSON.stringify(vote));
+  assert.ok(readGroupKeyFile(c.dir).members[b.peerId], '成员侧必须把对端补回成员表');
+});
+
+test('⑥ 轮换后 epoch 不回退：重启（新的 server 实例读同一份状态）时角色 epoch 不小于 keyVersion', async (t) => {
+  const cluster = await startCluster(t, { count: 2, heartbeatMs: 5_000, tickMs: 60_000 });
+  const [hub] = cluster.nodes;
+  hub.server.group.addMember('peer-ghost-2', 'ghost');
+  hub.server.group.removeMember('peer-ghost-2');
+  const keyVersion = hub.server.group.state().keyVersion;
+  assert.ok(keyVersion >= 2);
+  // 同一份 stateDir 再起一个实例（等价于重启）：角色 epoch 必须 ≥ keyVersion
+  const { createPeerServer } = await import('../server.mjs');
+  const restarted = createPeerServer({
+    listenHost: '127.0.0.1',
+    stateDir: hub.dir,
+    requireEncryption: false,
+    group: { enabled: true, name: 's3', quorum: 'none', heartbeatMs: 5_000 },
+    groupElection: { heartbeatMs: 5_000, tickMs: 60_000, peerTimeoutMs: 200 },
+  });
+  t.after(async () => { await restarted.close(); });
+  const info = await restarted.listen(0, '127.0.0.1');
+  assert.equal(info.port > 0, true);
+  const role = restarted.group.role();
+  assert.ok(role.epoch >= keyVersion, '角色 epoch 不得小于 keyVersion，实际 ' + role.epoch + ' vs ' + keyVersion);
+});
+

package/host/test/group-takeover.test.mjs

@@ -0,0 +1,122 @@
+/**
+ * v0.7.0 S3 补充 · 受限的启动竞选（priority-takeover）。
+ *
+ * 契约 §4 是「epoch 高者胜，同 epoch 才比 priority」——优先级不能跨 epoch 夺权，
+ * 于是优先节点重启期间被别人抢到更高 epoch 后会永久当 follower。这里给它一次有边界的重试权：
+ * 配置上没有 group.hub 的本机，启动稳定 2×heartbeatMs 后、优先级**严格更高**时尝试一次。
+ *
+ * 覆盖：①一次成功接管（epoch+1，原 leader 降级）②priority 相等不触发
+ *      ③接管失败后推进 30s 也不重试 ④配了 group.hub 的成员不触发
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { roleOf, startCluster, waitFor } from './group-cluster.mjs';
+
+const takeoverOf = (node) => node.server.group.takeover();
+
+const electionLines = (lines, kind) => lines
+  .filter((line) => line.includes('[group] election ' + kind) && line.includes('reason=priority-takeover'));
+
+test('S3 启动接管：高优先节点一次接管成功（epoch+1），原 leader 降级', async (t) => {
+  const lines = [];
+  const cluster = await startCluster(t, {
+    count: 2,
+    // 两台都是 hub 角色（配置上没有 group.hub），才有接管资格
+    hubRoles: [0, 1],
+    // 低优先（10）先当 leader；高优先（0）以 follower 起步
+    priorities: [10, 0],
+    followerOf: { 1: 0 },
+    logger: (line) => lines.push(String(line)),
+  });
+  const [low, high] = cluster.nodes;
+  assert.equal(roleOf(low).role, 'leader');
+  assert.equal(roleOf(high).role, 'follower');
+  assert.equal(roleOf(high).leaderPeerId, low.peerId);
+  assert.equal(takeoverOf(high).attempts, 0, '刚开始还不该动手');
+
+  await waitFor(() => takeoverOf(high).attempts === 1, { timeoutMs: 5_000 });
+  await waitFor(() => roleOf(high).role === 'leader', { timeoutMs: 5_000 });
+  await waitFor(() => roleOf(low).leaderPeerId === high.peerId, { timeoutMs: 5_000 });
+
+  assert.equal(roleOf(high).epoch, 2, '接管必须抬 epoch');
+  assert.equal(roleOf(low).role, 'follower');
+  assert.equal(roleOf(low).epoch, 2);
+  assert.equal(takeoverOf(high).attempts, 1);
+  assert.equal(takeoverOf(high).attempted, true);
+
+  const text = lines.join('\n');
+  assert.match(text, /\[group\] takeover attempt epoch=2 priority=0 leaderPriority=10/);
+  assert.equal(electionLines(lines, 'won').length, 1, '一次成功接管要留一行带票数的日志');
+  assert.match(text, /\[group\] takeover won epoch=2 votes=2\/2/);
+
+  // 稳定后不再重试：推进到远超过稳定期，attempts 仍然是 1
+  await sleep(400);
+  assert.equal(takeoverOf(high).attempts, 1);
+  assert.equal(electionLines(lines, 'won').length, 1);
+});
+
+test('S3 启动接管：priority 相等时一律不触发', async (t) => {
+  const cluster = await startCluster(t, {
+    count: 2,
+    hubRoles: [0, 1],
+    priorities: [0, 0],
+    followerOf: { 1: 0 },
+  });
+  const [low, high] = cluster.nodes;
+  // 等过稳定期（2×heartbeat=240ms）再多等几轮 tick
+  await sleep(700);
+  assert.equal(takeoverOf(high).attempts, 0, '优先级相等不得夺权');
+  assert.equal(takeoverOf(high).attempted, false);
+  assert.equal(roleOf(high).role, 'follower');
+  assert.equal(roleOf(high).leaderPeerId, low.peerId);
+  assert.equal(roleOf(low).role, 'leader');
+});
+
+test('S3 启动接管：失败一次后不再重试（假时钟推进 30s，接管仍只有 1 次）', async (t) => {
+  let fake = Date.now();
+  const clock = () => fake;
+  const lines = [];
+  const cluster = await startCluster(t, {
+    count: 2,
+    hubRoles: [0, 1],
+    priorities: [10, 0],
+    followerOf: { 1: 0 },
+    // 心跳放慢，好让「稳定期」在假时钟里可控（租约 = 3×400 = 1200ms）
+    heartbeatMs: 400,
+    tickMs: 25,
+    now: clock,
+    logger: (line) => lines.push(String(line)),
+  });
+  const [low, high] = cluster.nodes;
+  // 让 low 的心跳把「leader 优先级=10」教给 high（假时钟下真实时间照样走几轮）
+  await sleep(600);
+  assert.equal(takeoverOf(high).attempts, 0, '还没到稳定期（2×400=800ms）');
+
+  // 把 leader 打死，再跨过稳定期：这一枪注定落空
+  await low.server.close();
+  fake += 900;
+  await waitFor(() => takeoverOf(high).attempts === 1, { timeoutMs: 3_000 });
+  assert.equal(roleOf(high).role, 'follower', '失败后不得成为 leader');
+  assert.equal(electionLines(lines, 'lost').length, 1);
+  assert.match(lines.join('\n'), /\[group\] takeover lost epoch=2 votes=1\/2/);
+
+  // 推进 30s：普通租约过期选举可以重试，但**接管**必须一次就停
+  fake += 30_000;
+  await sleep(400);
+  assert.equal(takeoverOf(high).attempts, 1, '接管每进程只允许一次');
+  assert.equal(electionLines(lines, 'lost').length, 1);
+  assert.equal(electionLines(lines, 'won').length, 0);
+});
+
+test('S3 启动接管：配了 group.hub 的成员节点不触发（即使优先级更高）', async (t) => {
+  const cluster = await startCluster(t, { count: 2, priorities: [10, 0] });
+  const [low, member] = cluster.nodes;
+  assert.equal(low.server.group.isHub, true);
+  assert.equal(member.server.group.isHub, false);
+  await sleep(700);
+  assert.equal(takeoverOf(member).attempts, 0, '成员节点（配置了 group.hub）不得夺权');
+  assert.equal(roleOf(member).role, 'follower');
+  assert.equal(roleOf(low).role, 'leader');
+});
+

package/host/test/group.test.mjs

@@ -278,7 +278,8 @@ test('§4 hub 首次初始化：group.json 0600、hub 自己是成员、管理
   const raw = JSON.parse(fs.readFileSync(groupFile, 'utf8'));
   // S3 §5：group.json 追加 pending（未提交区，与 messages 分开存）
   assert.deepEqual(Object.keys(raw).sort(), [
-    'createdAt', 'groupId', 'key', 'keyVersion', 'lastSeq', 'members', 'messages', 'name', 'pending',
+    // blocked：被移除的成员（自助 join 不得把 ta 加回来）
+    'blocked', 'createdAt', 'groupId', 'key', 'keyVersion', 'lastSeq', 'members', 'messages', 'name', 'pending',
   ]);
   assert.equal(Buffer.from(raw.key, 'base64url').length, 32);
   assert.equal(raw.name, 'team');