test: extend yonexus integration coverage

TASKLIST.md

@@ -1052,7 +1052,7 @@
 
 ### YNX-1104 编写 Server-Client 集成测试
 **状态**
-- [x] 框架已完成（2026-04-09）
+- [x] 已完成（2026-04-09）
 
 **目标**
 - 覆盖首次配对、正常重连、认证失败、心跳超时、re-pair
@@ -1061,13 +1061,16 @@
 - 已创建 `tests/integration/framework.test.ts` 集成测试框架
 - 提供 `MockTransportPair` 模拟 Server-Client 网络通信
 - 提供 `createIntegrationTestContext()` 快速创建集成测试环境
-- 实现首批集成测试用例：
+- 已修正集成测试框架中的时间推进问题，`advanceTime()` 现在会真实驱动 Server / Client runtime 的 `now()`
+- 已实现以下集成测试用例：
   - 首次配对完整流程（hello → pair_request → pair_confirm → auth → heartbeat）
   - 带凭证的重连流程（跳过配对直接认证）
-  - 心跳交换验证
+  - 认证后的心跳交换验证
+  - 心跳超时触发 `unstable` / `offline` 与 `disconnect_notice`
+  - nonce collision 触发 `re_pair_required` 后 client 回退到 `pair_required`
 
 **待完成**
-- 更多边界场景：心跳超时断线、re-pair 触发、并发连接
+- 并发连接等剩余边界场景
 - 真实 WebSocket 传输层集成测试（可选）
 
 ---
@@ -1090,7 +1093,7 @@
 
 ### YNX-1105 编写失败路径测试矩阵
 **状态**
-- [x] 框架与 PF 测试已完成（2026-04-09）
+- [x] 部分关键路径已完成，仍有少量尾项（2026-04-09）
 
 **目标**
 - 系统性覆盖 pairing/auth 失败路径
@@ -1130,14 +1133,18 @@
   - Edge Cases: 并发配对、过期清理验证
 
 - 已新增 `Yonexus.Server/tests/auth-failures.test.ts`
-  - AF-07: nonce collision 触发 re_pair_required
-  - AF-08: rate limit 触发 re_pair_required
+  - AF-01 / AF-02：unknown identifier、not_paired
+  - AF-03 / AF-09 / AF-11：invalid signature、wrong public key、tampered proof
+  - AF-05 / AF-06：stale / future timestamp
+  - AF-07 / AF-08：nonce collision / rate limit 触发 re_pair_required
+  - AF-10：malformed auth_request payload
   - 覆盖 re_pair 后 secret 清理与 pairingStatus=revoked
+- 已同步更新 `tests/failure-path/MATRIX.md` 的 PF / AF / RP / HF 状态标记与当前备注
 
 **待完成**
-- AF（Authentication Failures）剩余场景（stale/future timestamp、invalid signature 等）
-- RP（Re-pairing Triggers）测试套件
-- CF/HF/SR 边界场景测试
+- AF-04：当前实现未单独暴露 `invalid_secret` 分支，需先决定是否保留该错误码语义
+- RP 其余触发场景
+- CF / HF / SR 其余边界场景测试
 
 ---
 

tests/failure-path/MATRIX.md

@@ -15,13 +15,13 @@ This document defines the systematic test coverage for pairing and authenticatio
 
 | ID | Scenario | Trigger | Expected Behavior | Status |
 |----|----------|---------|-------------------|--------|
-| PF-01 | Invalid pairing code | Client submits wrong code | `pair_failed(invalid_code)`, allow retry | ⬜ |
-| PF-02 | Expired pairing code | Client submits after expiry | `pair_failed(expired)`, reset to `pair_required` | ⬜ |
-| PF-03 | Identifier not in allowlist | Unknown client tries to pair | `pair_failed(identifier_not_allowed)`, close connection | ⬜ |
-| PF-04 | Admin notification failed | Discord DM fails to send | `pair_failed(admin_notification_failed)`, abort pairing | ⬜ |
-| PF-05 | Empty pairing code | Client submits empty string | `pair_failed(invalid_code)` | ⬜ |
-| PF-06 | Malformed pair_confirm payload | Missing required fields | Protocol error, no state change | ⬜ |
-| PF-07 | Double pairing attempt | Client calls pair_confirm twice | Second attempt rejected if already paired | ⬜ |
+| PF-01 | Invalid pairing code | Client submits wrong code | `pair_failed(invalid_code)`, allow retry | ✅ |
+| PF-02 | Expired pairing code | Client submits after expiry | `pair_failed(expired)`, reset to `pair_required` | ✅ |
+| PF-03 | Identifier not in allowlist | Unknown client tries to pair | `pair_failed(identifier_not_allowed)`, close connection | ✅ |
+| PF-04 | Admin notification failed | Discord DM fails to send | `pair_failed(admin_notification_failed)`, abort pairing | ✅ |
+| PF-05 | Empty pairing code | Client submits empty string | `pair_failed(invalid_code)` | ✅ |
+| PF-06 | Malformed pair_confirm payload | Missing required fields | Protocol error, no state change | ✅ |
+| PF-07 | Double pairing attempt | Client calls pair_confirm twice | Second attempt rejected if already paired | ✅ |
 | PF-08 | Pairing during active session | Paired client tries to pair again | Reject, maintain existing trust | ⬜ |
 | PF-09 | Server restart during pairing | Server restarts before confirm | Pairing state preserved, code still valid | ⬜ |
 | PF-10 | Client restart during pairing | Client restarts before submit | Client must restart pairing flow | ⬜ |
@@ -32,17 +32,17 @@ This document defines the systematic test coverage for pairing and authenticatio
 
 | ID | Scenario | Trigger | Expected Behavior | Status |
 |----|----------|---------|-------------------|--------|
-| AF-01 | Unknown identifier | Auth from unpaired client | `auth_failed(unknown_identifier)` | ⬜ |
-| AF-02 | Not paired | Auth before pairing complete | `auth_failed(not_paired)` | ⬜ |
-| AF-03 | Invalid signature | Wrong private key used | `auth_failed(invalid_signature)` | ⬜ |
+| AF-01 | Unknown identifier | Auth from unpaired client | `auth_failed(unknown_identifier)` | ✅ |
+| AF-02 | Not paired | Auth before pairing complete | `auth_failed(not_paired)` | ✅ |
+| AF-03 | Invalid signature | Wrong private key used | `auth_failed(invalid_signature)` | ✅ |
 | AF-04 | Wrong secret | Client has outdated secret | `auth_failed(invalid_secret)` | ⬜ |
-| AF-05 | Stale timestamp | Proof timestamp >10s old | `auth_failed(stale_timestamp)` | ⬜ |
-| AF-06 | Future timestamp | Proof timestamp in future | `auth_failed(future_timestamp)` | ⬜ |
+| AF-05 | Stale timestamp | Proof timestamp >10s old | `auth_failed(stale_timestamp)` | ✅ |
+| AF-06 | Future timestamp | Proof timestamp in future | `auth_failed(future_timestamp)` | ✅ |
 | AF-07 | Nonce collision | Reused nonce within window | `auth_failed(nonce_collision)` → `re_pair_required` 🔴 | ✅ |
 | AF-08 | Rate limited | >10 attempts in 10s | `auth_failed(rate_limited)` → `re_pair_required` 🔴 | ✅ |
-| AF-09 | Wrong public key | Key doesn't match stored | `auth_failed(invalid_signature)` | ⬜ |
-| AF-10 | Malformed auth_request | Missing required fields | Protocol error | ⬜ |
-| AF-11 | Tampered proof | Modified signature | `auth_failed(invalid_signature)` | ⬜ |
+| AF-09 | Wrong public key | Key doesn't match stored | `auth_failed(invalid_signature)` | ✅ |
+| AF-10 | Malformed auth_request | Missing required fields | Protocol error | ✅ |
+| AF-11 | Tampered proof | Modified signature | `auth_failed(invalid_signature)` | ✅ |
 
 ---
 
@@ -50,7 +50,7 @@ This document defines the systematic test coverage for pairing and authenticatio
 
 | ID | Scenario | Cause | Server Action | Client Action | Status |
 |----|----------|-------|---------------|---------------|--------|
-| RP-01 | Nonce collision | Replay attack detected | Clear secret, reset state | Enter `pair_required` | ⬜ |
+| RP-01 | Nonce collision | Replay attack detected | Clear secret, reset state | Enter `pair_required` | ✅ |
 | RP-02 | Rate limit exceeded | Brute force detected | Clear secret, reset state | Enter `pair_required` | ⬜ |
 | RP-03 | Admin-initiated | Manual revocation | Mark revoked, notify | Enter `pair_required` | ⬜ |
 | RP-04 | Key rotation | Client sends new public key | Update key, keep secret | Continue with new key | ⬜ |
@@ -75,8 +75,8 @@ This document defines the systematic test coverage for pairing and authenticatio
 
 | ID | Scenario | Trigger | Expected Behavior | Status |
 |----|----------|---------|-------------------|--------|
-| HF-01 | 7-minute timeout | No heartbeat received | Status → `unstable`, notify | ⬜ |
-| HF-02 | 11-minute timeout | Still no heartbeat | Status → `offline`, disconnect | ⬜ |
+| HF-01 | 7-minute timeout | No heartbeat received | Status → `unstable`, notify | ✅ |
+| HF-02 | 11-minute timeout | Still no heartbeat | Status → `offline`, disconnect | ✅ |
 | HF-03 | Early heartbeat | Heartbeat before auth | Rejected/ignored | ⬜ |
 | HF-04 | Heartbeat from unauthenticated | Wrong state | Error, possible disconnect | ⬜ |
 
@@ -130,6 +130,11 @@ npm test -- connection-failures
 npm test -- failure-paths
 ```
 
+### Current Notes
+
+- AF-04 (`invalid_secret`) 仍未单独覆盖：现有实现把“错误 secret 导致的验签失败”统一落到 `invalid_signature`，是否拆分错误码仍待确认。
+- 本轮已补齐 AF-01/02/03/05/06/09/10/11、RP-01、HF-01/02。
+
 ### Adding New Test Cases
 
 1. Add row to appropriate table above

tests/integration/framework.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
-import type { ClientConnection, ServerTransport } from "../Yonexus.Server/plugin/core/transport.js";
-import type { ClientTransport } from "../Yonexus.Client/plugin/core/transport.js";
-import type { YonexusServerStore } from "../Yonexus.Server/plugin/core/store.js";
-import type { YonexusClientStateStore } from "../Yonexus.Client/plugin/core/state.js";
-import { createYonexusServerRuntime } from "../Yonexus.Server/plugin/core/runtime.js";
-import { createYonexusClientRuntime } from "../Yonexus.Client/plugin/core/runtime.js";
+import type { ClientConnection, ServerTransport } from "../../Yonexus.Server/plugin/core/transport.js";
+import type { ClientTransport } from "../../Yonexus.Client/plugin/core/transport.js";
+import type { YonexusServerStore } from "../../Yonexus.Server/plugin/core/store.js";
+import type { YonexusClientStateStore } from "../../Yonexus.Client/plugin/core/state.js";
+import { createYonexusServerRuntime } from "../../Yonexus.Server/plugin/core/runtime.js";
+import { createYonexusClientRuntime } from "../../Yonexus.Client/plugin/core/runtime.js";
 import {
   decodeBuiltin,
   encodeBuiltin,
@@ -17,11 +17,12 @@ import {
   buildAuthSuccess,
   buildHeartbeat,
   buildHeartbeatAck,
+  createAuthRequestSigningInput,
   YONEXUS_PROTOCOL_VERSION
-} from "../Yonexus.Protocol/src/index.js";
-import { generateKeyPair } from "../Yonexus.Client/plugin/crypto/keypair.js";
-import type { ClientRecord } from "../Yonexus.Server/plugin/core/persistence.js";
-import type { YonexusClientState } from "../Yonexus.Client/plugin/core/state.js";
+} from "../../Yonexus.Protocol/src/index.js";
+import { generateKeyPair, signMessage } from "../../Yonexus.Client/plugin/crypto/keypair.js";
+import type { ClientRecord } from "../../Yonexus.Server/plugin/core/persistence.js";
+import type { YonexusClientState } from "../../Yonexus.Client/plugin/core/state.js";
 
 /**
  * Yonexus Server-Client Integration Test Framework
@@ -118,7 +119,7 @@ export function createMockTransportPair(): MockTransportPair {
   };
 
   // Client Transport Mock
-  let clientState: import("../Yonexus.Client/plugin/core/transport.js").ClientConnectionState = "idle";
+  let clientState: import("../../Yonexus.Client/plugin/core/transport.js").ClientConnectionState = "idle";
 
   const clientTransport: ClientTransport = {
     get state() {
@@ -244,18 +245,22 @@ export async function createIntegrationTestContext(
     paired?: boolean;
     authenticated?: boolean;
     serverTime?: number;
+    initialClientState?: Partial<YonexusClientState>;
+    initialServerClients?: ClientRecord[];
   } = {}
 ): Promise<IntegrationTestContext> {
-  const now = options.serverTime ?? 1_710_000_000;
+  const initialNow = options.serverTime ?? 1_710_000_000;
   const identifier = options.clientIdentifier ?? "test-client";
 
   const transports = createMockTransportPair();
-  const serverStore = createMockServerStore();
-  const clientStore = createMockClientStore({ identifier });
+  const serverStore = createMockServerStore(options.initialServerClients ?? []);
+  const clientStore = createMockClientStore({ identifier, ...options.initialClientState });
 
   // Generate keypair for client if needed
   const keyPair = await generateKeyPair();
 
+  let currentTime = initialNow;
+
   const serverRuntime = createYonexusServerRuntime({
     config: {
       followerIdentifiers: [identifier],
@@ -266,7 +271,7 @@ export async function createIntegrationTestContext(
     },
     store: serverStore,
     transport: transports.serverTransport,
-    now: () => now
+    now: () => currentTime
   });
 
   const clientRuntime = createYonexusClientRuntime({
@@ -278,12 +283,10 @@ export async function createIntegrationTestContext(
     },
     transport: transports.clientTransport,
     stateStore: clientStore,
-    now: () => now
+    now: () => currentTime
   });
 
   await serverRuntime.start();
-
-  let currentTime = now;
   const advanceTime = (seconds: number) => {
     currentTime += seconds;
   };
@@ -398,26 +401,27 @@ describe("Yonexus Server-Client Integration", () => {
       const ctx = await createIntegrationTestContext({
         clientIdentifier: "reconnect-client",
         paired: true,
-        authenticated: false
-      });
-
-      // Pre-populate client with existing credentials
-      ctx.clientRuntime.state.clientState.secret = "existing-secret";
-      ctx.clientRuntime.state.clientState.publicKey = keyPair.publicKey;
-      ctx.clientRuntime.state.clientState.privateKey = keyPair.privateKey;
-      ctx.clientRuntime.state.clientState.pairedAt = now - 1000;
-
-      // Pre-populate server with client record
-      ctx.serverRuntime.state.registry.clients.set("reconnect-client", {
-        identifier: "reconnect-client",
-        pairingStatus: "paired",
-        publicKey: keyPair.publicKey,
-        secret: "existing-secret",
-        status: "offline",
-        recentNonces: [],
-        recentHandshakeAttempts: [],
-        createdAt: now - 2000,
-        updatedAt: now - 1000
+        authenticated: false,
+        initialClientState: {
+          secret: "existing-secret",
+          publicKey: keyPair.publicKey.trim(),
+          privateKey: keyPair.privateKey,
+          pairedAt: now - 1000,
+          updatedAt: now - 1000
+        },
+        initialServerClients: [
+          {
+            identifier: "reconnect-client",
+            pairingStatus: "paired",
+            publicKey: keyPair.publicKey.trim(),
+            secret: "existing-secret",
+            status: "offline",
+            recentNonces: [],
+            recentHandshakeAttempts: [],
+            createdAt: now - 2000,
+            updatedAt: now - 1000
+          }
+        ]
       });
 
       // Connect and send hello
@@ -442,25 +446,185 @@ describe("Yonexus Server-Client Integration", () => {
 
   describe("Heartbeat Flow", () => {
     it("exchanges heartbeats after authentication", async () => {
+      const now = 1_710_000_000;
+      const keyPair = await generateKeyPair();
       const ctx = await createIntegrationTestContext({
         clientIdentifier: "heartbeat-client",
-        paired: true,
-        authenticated: true
+        serverTime: now,
+        initialClientState: {
+          secret: "existing-secret",
+          publicKey: keyPair.publicKey.trim(),
+          privateKey: keyPair.privateKey,
+          pairedAt: now - 1000,
+          updatedAt: now - 1000
+        },
+        initialServerClients: [
+          {
+            identifier: "heartbeat-client",
+            pairingStatus: "paired",
+            publicKey: keyPair.publicKey.trim(),
+            secret: "existing-secret",
+            status: "offline",
+            recentNonces: [],
+            recentHandshakeAttempts: [],
+            createdAt: now - 2000,
+            updatedAt: now - 1000
+          }
+        ]
       });
 
-      // Manually set authenticated state
-      ctx.clientRuntime.state.phase = "authenticated";
+      await ctx.clientRuntime.start();
+      ctx.clientRuntime.handleTransportStateChange("connected");
+      await vi.advanceTimersByTimeAsync(100);
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+      await vi.advanceTimersByTimeAsync(100);
+      await ctx.processClientToServer();
+      await ctx.processServerToClient();
+
+      expect(ctx.clientRuntime.state.phase).toBe("authenticated");
 
-      // Trigger heartbeat
       await ctx.clientRuntime.handleMessage("heartbeat_tick");
       await vi.advanceTimersByTimeAsync(100);
-
-      // Process heartbeat -> heartbeat_ack
       await ctx.processClientToServer();
 
-      // Verify server updated heartbeat timestamp
       const record = ctx.serverRuntime.state.registry.clients.get("heartbeat-client");
       expect(record?.lastHeartbeatAt).toBeDefined();
     });
+
+    it("marks client unstable then offline after heartbeat timeout", async () => {
+      const now = 1_710_000_000;
+      const keyPair = await generateKeyPair();
+      const ctx = await createIntegrationTestContext({
+        clientIdentifier: "timed-out-client",
+        serverTime: now
+      });
+
+      ctx.serverRuntime.state.registry.clients.set("timed-out-client", {
+        identifier: "timed-out-client",
+        pairingStatus: "paired",
+        publicKey: keyPair.publicKey.trim(),
+        secret: "existing-secret",
+        status: "online",
+        recentNonces: [],
+        recentHandshakeAttempts: [],
+        lastAuthenticatedAt: now,
+        lastHeartbeatAt: now,
+        createdAt: now - 100,
+        updatedAt: now
+      });
+      ctx.serverRuntime.state.registry.sessions.set("timed-out-client", {
+        identifier: "timed-out-client",
+        socket: { close: vi.fn() } as unknown as WebSocket,
+        isAuthenticated: true,
+        connectedAt: now,
+        lastActivityAt: now,
+        publicKey: keyPair.publicKey.trim()
+      });
+      ctx.transports.serverTransport.connections.set("timed-out-client", {
+        identifier: "timed-out-client",
+        ws: { close: vi.fn() } as unknown as WebSocket,
+        connectedAt: now,
+        isAuthenticated: true
+      });
+
+      ctx.advanceTime(7 * 60);
+      await vi.advanceTimersByTimeAsync(30_100);
+
+      const unstableRecord = ctx.serverRuntime.state.registry.clients.get("timed-out-client");
+      expect(unstableRecord?.status).toBe("unstable");
+      expect(ctx.transports.channel.serverToClient.some((message) => {
+        const envelope = decodeBuiltin(message);
+        return envelope.type === "status_update";
+      })).toBe(true);
+
+      ctx.advanceTime(4 * 60);
+      await vi.advanceTimersByTimeAsync(30_100);
+
+      const offlineRecord = ctx.serverRuntime.state.registry.clients.get("timed-out-client");
+      expect(offlineRecord?.status).toBe("offline");
+      expect(ctx.serverRuntime.state.registry.sessions.has("timed-out-client")).toBe(false);
+      expect(ctx.transports.channel.serverToClient.some((message) => {
+        const envelope = decodeBuiltin(message);
+        return envelope.type === "disconnect_notice";
+      })).toBe(true);
+    });
+  });
+
+  describe("Re-pair Flow", () => {
+    it("forces client back to pair_required after nonce collision", async () => {
+      const now = 1_710_000_000;
+      const keyPair = await generateKeyPair();
+      const collisionNonce = "NONCE1234567890123456789";
+      const ctx = await createIntegrationTestContext({
+        clientIdentifier: "collision-client",
+        serverTime: now,
+        initialClientState: {
+          secret: "existing-secret",
+          publicKey: keyPair.publicKey.trim(),
+          privateKey: keyPair.privateKey,
+          pairedAt: now - 100,
+          updatedAt: now - 100
+        },
+        initialServerClients: [
+          {
+            identifier: "collision-client",
+            pairingStatus: "paired",
+            publicKey: keyPair.publicKey.trim(),
+            secret: "existing-secret",
+            status: "offline",
+            recentNonces: [{ nonce: collisionNonce, timestamp: now - 1 }],
+            recentHandshakeAttempts: [],
+            createdAt: now - 200,
+            updatedAt: now - 100
+          }
+        ]
+      });
+
+      ctx.serverRuntime.state.registry.sessions.set("collision-client", {
+        identifier: "collision-client",
+        socket: { close: vi.fn() } as unknown as WebSocket,
+        isAuthenticated: false,
+        connectedAt: now,
+        lastActivityAt: now,
+        publicKey: keyPair.publicKey.trim()
+      });
+
+      const authRequest = buildAuthRequest(
+        {
+          identifier: "collision-client",
+          nonce: collisionNonce,
+          proofTimestamp: now,
+          signature: await signMessage(
+            keyPair.privateKey,
+            createAuthRequestSigningInput({
+              secret: "existing-secret",
+              nonce: collisionNonce,
+              proofTimestamp: now
+            })
+          ),
+          publicKey: keyPair.publicKey.trim()
+        },
+        { requestId: "req-collision", timestamp: now }
+      );
+
+      await ctx.serverRuntime.handleMessage(
+        {
+          identifier: "collision-client",
+          ws: { close: vi.fn() } as unknown as WebSocket,
+          connectedAt: now,
+          isAuthenticated: false
+        },
+        encodeBuiltin(authRequest)
+      );
+
+      const serverEnvelope = decodeBuiltin(ctx.transports.channel.serverToClient.at(-1) ?? "");
+      expect(serverEnvelope.type).toBe("re_pair_required");
+
+      await ctx.clientRuntime.handleMessage(ctx.transports.channel.serverToClient.at(-1)!);
+      expect(ctx.clientRuntime.state.phase).toBe("pair_required");
+      expect(ctx.clientRuntime.state.clientState.secret).toBeUndefined();
+      expect(ctx.clientRuntime.state.lastPairingFailure).toBe("re_pair_required");
+    });
   });
 });